Interactive  Raytracing:  The  nirt  Command 


by  Clifford  Yapp 


ARL-CR-624 


April  2009 


prepared  by 

Quantum  Research  International,  Inc. 
2014  Tollgate  Rd.,  Ste.  203 
Bel  Air,  MD  21015 

under  contract 

W911QX-06-F-0057 


Approved  for  public  release;  distribution  is  unlimited. 


NOTICES 

Disclaimers 

The  findings  in  this  report  are  not  to  be  construed  as  an  official  Department  of  the  Army  position  unless 
so  designated  by  other  authorized  documents. 

Citation  of  manufacturer’s  or  trade  names  does  not  constitute  an  official  endorsement  or  approval  of  the 
use  thereof. 


Destroy  this  report  when  it  is  no  longer  needed.  Do  not  return  it  to  the  originator. 


Army  Research  Laboratory 

Aberdeen  Proving  Ground,  MD  21005-5068 


ARL-CR-624 


April  2009 


Interactive  Raytracing:  The  nirt  Command 

Clifford  Yapp 

Quantum  Research  International,  Inc. 


Approved  for  public  release;  distribution  is  unlimited. 


REPORT  DOCUMENTATION  PAGE 


Form  Approved 
OMB  No.  0704-0188 


Public  reporting  burden  for  this  collection  of  information  is  estimated  to  average  1  hour  per  response,  including  the  time  for  reviewing  instructions,  searching  existing  data  sources,  gathering 
and  maintaining  the  data  needed,  and  completing  and  reviewing  the  collection  information.  Send  comments  regarding  this  burden  estimate  or  any  other  aspect  of  this  collection  of  information, 
including  suggestions  for  reducing  the  burden,  to  Department  of  Defense,  Washington  Headquarters  Services,  Directorate  for  Information  Operations  and  Reports  (0704-0188),  1215  Jefferson 
Davis  Highway,  Suite  1204,  Arlington,  VA  22202-4302.  Respondents  should  be  aware  that  notwithstanding  any  other  provision  of  law,  no  person  shall  be  subject  to  any  penalty  for  failing  to 
comply  with  a  collection  of  information  if  it  does  not  display  a  currently  valid  OMB  control  number. 

PLEASE  DO  NOT  RETURN  YOUR  FORM  TO  THE  ABOVE  ADDRESS. 


12.  DISTRIBUTION/AVAILABILITY  STATEMENT 

Approved  for  public  release;  distribution  is  unlimited. 

13.  SUPPLEMENTARY  NOTES 


14.  ABSTRACT 

The  nirt  command  casts  individual  rays  according  to  user-specified  options  and  reports  back  a  wide  variety  of  information 
about  the  model  along  the  specified  ray.  It  is  extremely  useful  for  tasks  such  as  measuring  the  thickness  of  objects  and 
identifying  gaps  between  objects.  When  used  within  the  multidevice  graphics  editor  environment,  NIRT  will  produce  a  visible 
ray  path,  coloring  the  ray  according  to  the  geometry  encountered  along  the  ray.  It  is  also  scriptable,  allowing  users  to  develop 
their  own  custom  analysis  routines. 


15.  SUBJECT  TERMS 

BRL-CAD,  raytracing,  nirt,  Natalie’s  Interactive  Ray-Tracer 

17.  LIMITATION  18.  NUMBER 
OF  ABSTRACT  OF  PAGES 

UU  58 

Standard  Form  298  (Rev.  8/98) 

Prescribed  by  ANSI  Std.  Z39.18 


19a.  NAME  OF  RESPONSIBLE  PERSON 

Michael  Gillich _ 

19b.  TELEPHONE  NUMBER  ( Include  area  code) 

410-278-7820 


16.  SECURITY  CLASSIFICATION  OF: 


a.  REPORT 

b.  ABSTRACT 

c.  THIS  PAGE 

Unclassified 

Unclassified 

Unclassified 

1 .  REPORT  DATE  (DD-MM-YYYY)  2.  REPORT  TYPE 

April  2009  Final 

4.  TITLE  AND  SUBTITLE 

Interactive  Ray  tracing:  The  nirt  Command 


6.  AUTHOR(S) 

Clifford  Yapp 


7.  PERFORMING  ORGANIZATION  NAME(S)  AND  ADDRESS(ES) 

Quantum  Research  International,  Inc. 

2014  Tollgate  Rd.,  Ste.  203 
Bel  Air,  MD  21015 

9.  SPONSORING/MONITORING  AGENCY  NAME(S)  AND  ADDRESS(ES) 

U.S.  Army  Research  Laboratory 

ATTN:  AMSRD- ARL- SL-B S 

Aberdeen  Proving  Ground,  MD  21005-5068 


3.  DATES  COVERED  (From  -  To) 

June  2008-October  2008 

5a.  CONTRACT  NUMBER 

W91 1QX-06-F-0057 

5b.  GRANT  NUMBER 

5c.  PROGRAM  ELEMENT  NUMBER 

5d.  PROJECT  NUMBER 

5e.  TASK  NUMBER 

5f.  WORK  UNIT  NUMBER 

8.  PERFORMING  ORGANIZATION 
REPORT  NUMBER 


10.  SPONSOR/MONITOR’S  ACRONYM(S) 

ARL 

11.  SPONSOR/MONITOR'S  REPORT 
NUMBER(S) 

ARL-CR-624 


11 


Contents 


List  of  Figures  v 

List  of  Tables  vi 

Acknowledgments  vii 

1.  About  NIRT  1 

2.  NIRT :  Basic  Syntax  and  Operations  1 

2. 1  Command  Line  Help . 1 

2.2  Loading  a  Model . 2 

2.3  Shooting  a  Ray . 3 

2.4  Moving  the  Origination  Point . 4 

2.5  Backing  Out  of  a  Model . 4 

2.6  Changing  the  Direction  of  the  Ray . 5 

2.7  Reporting  of  Overlaps . 6 

3.  Graphical  Visualization:  NIRT  in  MGED  7 

3.1  Basic  Usage . 8 

3.2  Backing  Out  With  NIRT  in  MGED . 9 

3.3  Ray  Segment  Coloring  With  NIRT  and  MGED . 10 

3.4  Mouse-Based  NIRT  Usage . 13 

4.  Configuring  NIRT  With  the  Query  Ray  Control  Panel  15 

4. 1  Enabling  and  Disabling  Mouse-Based  NIRT  Ray  Casting . 15 

4.2  Customizing  NIRT  Coloring  in  MGED . 16 

4.3  Customizing  the  Pseudo-Primitive  Base  Name . 1 7 

4.4  Echoing  the  Internal  nirt  Command . 19 

4.5  Selecting  Graphical  and  Textual  Output . 21 

5.  Reporting  Options  21 

5.1  How  to  Change  the  Reporting  Format . 21 

iii 


5.2  Handling  Attribute  Reporting . 24 

5.3  Changing  Units . 25 

6.  Other  Options  26 

6. 1  Silent  and  Verbose  Modes . 26 

6.2  Using  Air  Regions . 26 

6.3  Reading  an  Orientation  Matrix  and  Commands . 27 

7.  Scripting  NIRT  28 

7.1  Command  Line  Scripts:  The  e  Option . 28 

7.2  Script  Files:  Other  Uses  of  the/Option . 29 

7.3  Defining  a  Custom  Reporting  Format . 3 1 

7.4  Customizing  Report  Output  in  MGED . 32 

7.5  Reporting  Attributes  in  MGED:  Advanced  Formatting  and  Scripting . 33 

7.6  Available  Information  for  Inclusion  in  Reports . 34 

8.  Summary  35 

Appendix  A.  Debugging  Options  37 

Appendix  B.  Report  Format  Variable  Listings  41 

Distribution  List  44 


IV 


List  of  Figures 


Figure  1.  Wireframe  view  of  the  three  arb8  cubes  which  will  be  used  to  build  example 

models  for  illustrating  NIRT  behavior . 2 

Figure  2.  View  of  wireframe  immediately  after  running  NIRT  within  MGED . 8 

Figure  3.  View  of  wireframe  after  changing  view  direction,  showing  path  of  NIRT  ray . 9 

Figure  4.  View  of  NIRT  ray  intersecting  left_and_right_cubes.r  with  ray  origin  at  the  global 
origin . 10 

Figure  5.  View  of  NIRT  ray  intersecting  left_and_right_cubes.r  with  ray  origin  backed  out 

of  the  region . 10 

Figure  6.  Side  view  of  aligned  individual  arb8  cubes  with  a  single  NIRT  ray  passing  through 
all  three  cubes . 11 

Figure  7.  View  of  wireframe  of  three  arb8  cubes  combined  into  a  single  region  with  a  NIRT 
ray  passing  through  the  region  on  the  same  path  as  that  used  for  the  individual  arb8 
cubes . 12 

Figure  8.  View  of  ray  cast  through  only  left_cube.r  and  right_cube.r . 13 

Figure  9.  Example  of  an  overlap  region  in  a  NIRT  ray . 13 

Figure  10.  Grid  overlay  on  MGED  wireframe . 14 

Figure  11.  MGED’s  Query  Ray  Control  Panel  with  the  Mouse  Active  check  box  circled . 15 

Figure  12.  MGED’s  Query  Ray  Control  Panel  with  the  Query  Ray  Colors  circled . 16 

Figure  13.  MGED’s  Query  Ray  Control  Panel  with  an  example  color  list  selected . 17 

Figure  14.  MGED’s  color  tool . 17 

Figure  15.  Wireframe  view  of  a  NIRT  ray  using  multiple  colors . 18 

Figure  16.  Wireframe  view  of  the  NIRT  ray  after  erasing  query _rayff00ff. . 18 

Figure  17.  MGED’s  Query  Ray  Control  Panel  showing  a  new  Base  Name . 19 

Figure  18.  MGED’s  Query  Ray  Control  Panel  with  the  Echo  Cmd  check  box  circled . 20 

Figure  19.  MGED’s  Query  Ray  Control  Panel  with  the  Effects  drop-down  menu  shown . 21 

Figure  20.  Shot  command  output  file  imported  into  a  spreadsheet . 23 

Figure  21.  MGED’s  Query  Ray  Control  Panel  showing  the  Use  Air  check  box . 27 

Figure  22.  The  f  option  output  file  imported  into  a  spreadsheet . 3 1 

Figure  23.  MGED’s  Query  Ray  Advanced  Settings  dialog  box . 33 

Figure  24.  Query  Ray  Advanced  Settings  dialog  box  showing  changes  to  values  (white 

highlight) . 33 

Figure  25.  Adding  commands  to  the  Script  line  in  the  advanced  settings  dialog . 34 


v 


List  of  Tables 


Table  1.  NIRT  command  line  environments . 1 

Table  2.  Interactive  command  s  report  breakdown . 3 

Table  3.  Ray  segment  coloring  conventions . 11 

Table  4.  Report  event  types . 34 

Table  B-l.  Ray  variables . 42 

Table  B-2.  Partition  variables . 42 

Table  B-3.  Overlap  variables . 43 

Table  B-4.  Gap  variables . 43 


Acknowledgments 


The  author  would  like  to  thank  Bob  Parker,  John  Anderson,  Janine  Gettier,  and  Christopher  Sean 
Morrison  for  their  time  and  help  with  explaining  some  of  the  more  subtle  concepts  encountered 
by  the  author  during  the  creation  of  this  report. 


Intentionally  left  blank. 


1.  About  NIRT 


The  NIRT  (Natalie’s  Interactive  Ray-Tracer)  command  line  tool  provides  a  user-level  interface 
to  the  low-level  routines  defining  the  ray  tracing  logic,  allowing  a  user  to  specify  and  cast  an 
individual  ray  and  tailor  the  information  reported.  It  was  originally  written  by  Natalie  L.  Eberius 
and  Paul  J.  Tanenbaum  in  the  early  1990s,  with  additional  updates  by  others  over  the  years. 
Significant  work  was  done  by  Bob  Parker  in  the  late  1990s  to  integrate  NIRT  with  a  multidevice 
graphics  editor  (MGED),  resulting  in  wireframe  visualization  of  ray  paths  and  the  Query  Ray 
Control  Panel. 


2.  NIRT:  Basic  Syntax  and  Operations 


There  are  two  environments  within  which  NIRT  can  be  used — inside  the  MGED  interactive 
geometry  editor  and  within  its  own  command  line  interactive  environment.  Consequently,  there 
are  three  command  line  environments  where  behavior  needs  to  be  described  in  this  document: 
operating  system  command  prompt,  NIRT  command  prompt,  and  MGED  command  prompt 
(table  1). 


Table  1.  NIRT  command  line  environments. 


Command  Line  Environment 

Command  Type 

Operating  system  command  line  prompt 

Command 

NIRT  command  prompt 

Interactive  command 

MGED  command  prompt 

MGED  command 

2.1  Command  Line  Help 

NIRT  provides  an  h  option  which  prints  out  a  list  of  available  options  and  command  syntax: 

user  @ma  chine  ~  $  nirt  -  -  h 

Usage:  ‘nirt  [options]  model. g  objects...’ 

Opt i  o ns : 

-b  back  out  of  geo  me  try  before  first  shot 

-B  n  set  rt_bot_mi  npi  eces=n 

-e  script  run  script  before  interacting 
-f  sfile  run  script  sfile  before  interacting 
-L  list  output  formatting  options 

-  M  r  e  a  d  ma  t  r  i  x ,  c  md  s  o  n  s  t  d  i  n 

-0  action  handle  overlap  claims  via  action 
-s  run  in  silent  (non-verbose)  mode 

-u  n  set  use_air=n  (default  0) 

-v  run  in  verbose  mode 

-  x  v  set  librt(3)  diagnostic  flag=v 

-X  v  set  nirt  diagnostic  f  I  a  g  =v 
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2.2  Loading  a  Model 


There  will  be  a  number  of  models  used  to  illustrate  various  NIRT  behaviors,  all  of  which  will  be 
centered  around  regions  created  with  various  combinations  of  2-mm  arb8  cubes  (figure  1).  The 
left  cube  is  centered  at  (-2,  0,  0),  the  center  cube  at  (0,  0,  0),  and  the  right  cube  at  (2,  0,  0).  One 
additional  arb8  will  be  defined  to  overlap  the  center  cube  with  side  lengths  in  the  z  direction  of 
4  mm.  The  various  models  based  off  of  these  primitives  will  be  read  from  a  database  called 
ni  r  t  _ e x a  mp I  e.  g . 


Figure  1.  Wireframe  view  of  the  three  arb8 
cubes  which  will  be  used  to  build 
example  models  for  illustrating 
NIRT  behavior. 

Although  there  are  many  nirt  options  available,  only  the  database  name  and  objects  are  essential 
to  get  started: 

nirt  {  model  .  gj  {  objects} 

where  objects  is  a  list  of  objects  in  the  database  separated  by  spaces.  To  begin,  select  the  object 
center _cube.r  object  with  interactive  command  line  NIRT.  The  form  of  the  command  is:* 

nirt  nirt_example.g  center_cube.r 

This  starts  up  the  NIRT  command  line  interactive  environment: 

BRL-CAD  Release  7.13.0  Natalie’s  Interactive  Ray  Tracer 
Tue,  26  Aug  2008  23:21:32  -  0400,  Compilation  2 
u  s  e  r  @1  o  c  a  I  h  o  s  t  :  /  u  s  r  /  b  r  I  c  a  d 
Database  file:  ‘n  i  r  t  _  e  x  a  mp  I  e .  g  ’ 

Building  the  directory... 

Get  trees... 


*To  quickly  find  out  what  objects  are  in  a  database,  use  the  commands  mged  -c  nirt_example.g  tops  to  see  all  top-level 
objects  and  mged  -c  nirt_example.g  Is  to  see  all  objects  in  the  model. 
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Prepping  the  geo  me  try... 

Object  ‘c  e  nt  e  r  _  c  u  be .  r  ’  processed 
Database  title:  ‘Example  BRL-CAD  Database’ 

Database  units:  ‘mm’ 

mo  d  e  I  _  mi  n  =  ( -  1 ,  -  1 ,  -  1 )  mo  d  e  I  _  ma  x  =  (  1 ,  1 ,  1 ) 

n  i  r  t  > 

The  first  three  lines  identify  the  release  number,  tool  being  used,  date  of  compilation  or  date 
release  was  made,  and  user.  The  fourth  line  identifies  the  database  file.  The  next  three  lines  are 
informational  messages  relating  to  model  setup.  The  database  title  and  units  are  then  printed. 
The  last  pieces  of  information,  mo  del  mi  n  and  mo  d  e  I  _  ma  x ,  are  the  outer  bounds  of  the  objects 
specified. 

2.3  Shooting  a  Ray 

With  the  example  loaded  into  NIRT,  the  s  interactive  command  is  used  to  shoot  a  ray: 

n  i  r  t  >  s 

Origin  (x  y  z)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0)  (az  el)  =  (0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obliq_in  Attrib 

cent  er_cube.  r  (  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 


What  happened  and  what  do  these  results  mean?  Table  2  breaks  down  the  structure  of  the  report. 
Because  the  ray  only  hit  center_cube.r,  only  center_cube.r  appears  in  the  report.  (Remember, 
NIRT  was  only  supplied  with  center_cube.r  for  a  target  object  to  begin  with.)  Many  examples  of 
real-world  NIRT  usage  will  have  much  more  complex  geometries  and  hence  longer  reports. 


Table  2.  Interactive  command  s  report  breakdown. 


Report  Element 

Meaning 

Origin 

Origination  point  of  the  ray  (NOT  the  model  origin) 

x  y  z 

Coordinates  in  the  reference  frame  of  the  model 

h  v  d 

Coordinates  in  the  reference  frame  of  the  view 

Direction 

Direction  in  which  the  ray  is  traced;  reported  as  a  unit  vector  in  model 
coordinates  and  as  an  azimuth/elevation  angle  pair 

Region  name 

Name  of  region  as  recorded  in  database  file 

Entry  (x  y  z) 

Point  at  which  ray  first  enters  the  region 

LOS 

Line-of-sight  thickness.  In  this  basic  instance,  it  is  equivalent  to  the 
thickness  of  the  object  along  the  ray  vector. 

Obliq_in 

Obliquity  of  the  ray  at  the  point  of  entry  into  the  region  (0  in  this  case 
because  the  ray  happened  to  be  perpendicular  to  the  surface  in  question) 

Attrib 

Additional  attributes  the  region  in  question  has  assigned  and  the  user 
requested  (in  this  case,  none  were  requested) 
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2.4  Moving  the  Origination  Point 

If  we  move  the  origin  to  some  point  other  than  the  sphere  center,  a  different  ray  is  cast  and  the 
reported  intersections  change.  The  xyz  interactive  command  will  print  the  current  origin  if  given 
no  arguments  and  accept  a  list  of  points  to  change  the  origin: 


n  i  r  t  > 

xyz 

( X,  y, 

z)  =(0.00, 

0.  00, 

0.  00) 

n  i  r  t  > 

xyz  0  0  .  5 

n  i  r  t  > 

xyz 

( X,  y, 

z)  =(0.00, 

0.  00, 

0.  50) 

n  i  r  t  > 

s 

Origin  (x  y  z)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.5  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.5  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 

Region  Name  Entry  (xyz)  LOS  Obliq_in  Attrib 

cent  er_cube.  r  (  1.0  0  0  0  0.0  0  0  0  0.5  0  0  0  )  2.0  0  0  0  0.0  0  0  0 

2.5  Backing  Out  of  a  Model 

Although  in  both  previous  cases,  the  ray’s  origin  was  inside  the  cube,  NIRT  backed  up  to  the 
point  of  first  intersection  along  the  indicated  vector  to  report  both  LOS  thickness  and  entry.  This 
behavior  is  specific  to  the  case  of  an  origination  point  inside  a  region.  In  the  case  where  the 
origination  point  of  the  ray  is  between  two  objects  belonging  to  the  same  region,  NIRT  will 
report  only  those  portions  of  the  region  along  its  path  forward.  To  ensure  that  a  ray  always  starts 
outside  the  entire  geometry,  the  backout  interactive  command  is  used.*  The  backout  command 
moves  the  starting  point  outside  the  bounding  box  of  the  model.  This  ensures  that  all  segments 
along  a  given  ray  path  will  be  reported.  As  an  illustration,  reload  ni  rtexampl  e.  g  and  this 
time  specify  left_and_right_cubes.r  (defined  as  the  combination  of  left_cube.s  and  right _cube.s). 
Cast  rays  before  and  after  backout: 

n  i  r  t  >  q 
Quitting... 

user  @ma  chine  ~  $  nirt  ni  rt_exampl  e.  g  left_and_right_cubes.r 
BRL-CAD  Release  7.13.0  Natalie’s  Interactive  Ray  Tracer 
Tue,  26  Aug  2008  23:21:32  -  0400,  Compilation  2 
u  s  e  r  @1  o  c  a  I  h  o  s  t  :  /  u  s  r  /  b  r  I  c  a  d 
Database  file:  ‘n  i  r  t  _  exa  mp I  e .  g  ’ 

Building  the  directory... 

Get  trees... 

Prepping  the  geo  me  try... 

Object  ‘I  ef  t  _  a  nd_  r  i  g  ht  _  c  u  bes .  r  ’  processed 
Database  title:  ‘Example  BRL-CAD  Database’ 

Database  units:  ‘mm’ 

mo  d  e  I  _  mi  n  =  ( -  3 ,  -1,  -1)  mo  d  e  I  _  ma  x  =  (  3 ,  1,  1) 

n  i  r  t  >  s 

Origin  (x  y  z)  =  (0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 

Region  Name  Entry  (xyz)  LOS  Obi  i  q  _  i  n  Attrib 

I  ef  t  _  a  n  d  _  r  i  ght  _cubes .  r  (  -  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0  "  0  0  0  0 

nirt>  backout  1 
n  i  r  t  >  s 

Origin  (x  y  z)  =  (6.6  3  3  2  4  9  5  8  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0)  (az  el)  =  (0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 


*To  perform  this  operation  automatically  when  the  model  is  loaded,  supply  the  b  flag  to  nirt  at  startup:  nirt  -b. 
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Region  Name  Entry  (x  y  z)  LOS  Obliq_in  Attrib 

left  and  right  cubes. r  (  3.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  o7  0  0  0  0 

I  eft_and_ri  ght_cubes.  r  (  -  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0)  2.0  0  0  0  0.0  0  0  0 


In  the  first  raytrace,  left _and  right _cubes.r  did  not  backtrack  to  generate  its  LOS  thickness 
value,  and  when  the  backout  option  was  applied,  left_and_right_cubes.r  gained  an  extra  entry. 
The  double  report  for  left_and_right_cubes.r  is  not  a  mistake;  the  ray  did  indeed  enter  and  exit 
the  region  twice  once  the  backout  interactive  command  changed  the  origination  point. 

It  is  important  to  understand  that  the  backout  interactive  command  does  not  permanently  change 
the  origination  point  of  the  ray;  it  requests  an  automatic  adjustment  of  the  origination  point  based 
on  the  model  for  the  casting  of  the  ray  and  then  restores  the  original  specified  origination  point. 

If  the  user  no  longer  wishes  to  have  NIRT  back  the  origination  point  out  of  the  model, 
deactivating  the  backout  flag  (supplying  0  to  the  backout  interactive  command)  will  restore  the 
nonbackout  point.  If  the  xyz  interactive  command  is  used  to  change  the  origination  point  while 
backout  is  activated,  the  backout  routine  will  back  out  from  the  new  point.  For  example: 

nirt>  backout  0 
ni  r  t  >  xyz 

( x,  y,  z)  =  ( 0.  00,  0.  00,  0.  00) 

ni  r  t  >  xyz  0  0.5 
n  i  r  t  >  s 

Origin  (x  y  z)  =  (0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.5  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.5  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 

Region  Name  Entry  (xyz)  LOS  Obi  i  q  _  i  n  Attrib 

I  ef  t  _  a  n  d  _  r  i  ght  _cubes .  r  (  -  1.0  0  0  0  0.0  0  0  0  0.5  0  0  0  )  2.0  0  0  0  0  "  0  0  0  0 

nirt>  backout  1 
ni  r  t  >  xyz 

( x,  y,  z)  =  ( 0.  00,  0.  00,  0.  50) 

nirt>  backout  0 
ni  r  t  >  xyz 

( x,  y,  z)  =  (  0.  0  0,  0.  0  0,  0.  5  0  ) 

nirt>  backout  1 
ni  r  t  >  xyz  0  0.8 
n  i  r  t  >  s 

Origin  (x  y  z)  =  (  6.6  3  3  2  4  9  5  8  0.0  0  0  0  0  0  0  0  0.8  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.8  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  Attrib 

left  and  right  cubes. r  (  3.0  0  0  0  0.0  0  0  0  0.8  0  0  0  )  2.0  0  0  0  0  "  0  0  0  0 

I  ef  t_and_ri  ght_cubes.  r  (  -  1.0  0  0  0  0.0  0  0  0  0.8  0  0  0  )  2.0  0  0  0  0.0  0  0  0 

ni  r  t  >  backout  0 
n  i  r  t  >  s 

Origin  (x  y  z)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.8  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.8  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0)  (az  el)  =  (0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0) 

Region  Name  Entry  (xyz)  LOS  Obi  i  q  _  i  n  Attrib 

I  ef  t  _  a  n  d_  r  i  ght_cubes.  r  (  -  1.0  0  0  0  0.0  0  0  0  0.8  0  0  0  )  2.0  0  0  0  0  "  0  0  0  0 

n  i  r  t  > 


2.6  Changing  the  Direction  of  the  Ray 

The  other  fundamental  operation  needed  to  make  NIRT  usable  is  changing  the  direction  of  the 
ray.  This  is  achieved  with  the  dir  interactive  command,  which  either  prints  out  the  current 
direction  unit  vector  (if  no  arguments  are  supplied)  or  takes  x,  y,  and  z  components  of  a  vector 
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separated  by  spaces  and  changes  the  direction.  To  make  interpreting  the  results  easier  for  this 
example,  the  origination  point  of  the  ray  is  first  returned  to  the  origin: 


ni  r  t  >  xyz  0  0  0 
n  i  r  t  >  dir 


( x,  y,  z)  =(-  1.0  0,  0.  0  0,  0.  0  0) 
n  i  r  t  >  s 

Origin  (x  y  z)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 
Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0)  (az  el)  =  (-  0.0  0  0  0  0  0  0  0  -  0.0  0  0  0  0  0  0  0  ) 
Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  At  t  r  i  b 

I  eft_and_ri  ght_cubes.  r  (  -1.0000  0.0000  0.0000)  2.0000  0"0000 

nirt>  dir  -1  -  .5  0 
n  i  r  t  >  dir 

(x,  y,  z)  =  (-  0.  8  9,  -  0.  4  5,  0.  0  0  ) 
n  i  r  t  >  s 


Origin  (x  y  z)  =  (0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 
Direction  (x  y  z)  =  (-  0.8  9  4  4  2  7  1  9  -  0.4  4  7  2  1  3  6  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  2  6.5  6  5  0  5  1  1  8  -  0.0  0  0  0  0  0  0  0  ) 
Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  At  t  r  i  b 

I  eft_and_ri  ght_cubes.  r  (  -1.0000  -0.5000  0.0000)  1.1180  2675651 

n  i  r  t  >  d  i  r  0  0  1 


n  i  r  t  >  s 


Origin  (x  y  z)  =  (0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0)  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 
Direction  (x  y  z)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  1.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  -  9  0.0  0  0  0  0  0  0  0  ) 
You  missed  the  target 
n  i  r  t  > 


The  first  shot  in  the  default  -x  direction  intersects  one  of  the  sections.  The  second  shot  changes 
the  aim  slightly  off  the  -x  axis,  with  different  results — the  LOS  thickness  is  now  longer. 

Obi  i  q  _  i  n  changed  as  well  because  the  ray  is  no  longer  perpendicular  to  the  tangent  at  the  point 
of  intersection.  Notice  that  the  direction  was  not  specified  using  a  unit  vector  but  was  reported 
as  one;  the  conversion  to  a  unit  vector  is  handled  automatically  by  NIRT.  The  third  shot  is  a 
more  drastic  change  of  direction,  from  the  -x  to  positive  z.  As  there  are  no  portions  of  the  region 
present  along  that  path,  a  miss  is  reported. 

2.7  Reporting  of  Overlaps 

In  many  cases,  a  geometry  will  have  overlaps:  errors  where  a  model  is  assigning  two  physical 
regions  to  one  volume.  To  demonstrate  this  behavior,  NIRT  is  reloaded  with  overlap _example: 

n  i  r  t  >  q 
Quitting... 

user  @ma  chine  ~  $  nirt  ni  rt_exampl  e.  g  overl  ap_exampl  e 
BRL-CAD  Release  7.13.0  Natalie’s  Interactive  Ray  Tracer 
Tue,  26  Aug  2008  23:21:32  -  0400,  Compilation  2 
u  s  e  r  @1  o  c  a  I  h  o  s  t  :  /  u  s  r  /  b  r  I  c  a  d 
Database  file:  ‘n  i  r  t  _  exa  mp I  e .  g  ’ 

Building  the  directory... 

Get  trees... 

Prepping  the  geo  me  try... 

Object  ‘over  I  a  p  _  e  x  a  mp  I  e’  processed 
Database  title:  ‘Example  BRL-CAD  Database’ 

Database  units:  ‘mm’ 

mo  d  e  I  _  mi  n  =  ( -  3 ,  -1,  -2)  mo  d  e  I  _  ma  x  =  (  3 ,  1,  2) 

nirt>  backout  1 
n  i  r  t  >  s 

Origin  (x  y  z)  =  (7.4  8  3  3  1  4  7  7  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 
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Di  rect i  on  ( x  y  z)  =  ( -  1.  0  0  0  0  0  0  0  0  0.  0  0  0  0  0  0  0  0 
Region  Name  Entry(xyz) 

a  I  I  _ c  u  bes .  r  (  3.0  0  0  0  0.0  0  0  0 

OVERLAP:  ‘c e n t  e r  _ o v e r  I  a p .  r  ’  a  n d  ‘a I  I  _ c  u bes .  r  ’ 
n  i  r  t  > 


0.00000000)  (az  el)  =  (0.00000000  0.00000000) 
LOS  Obi  i  q _  i  n  At  t  r  i  b 
0.0  0  0  0)  6.0  0  0  0  0.0  0  0  0 
x y z _  i  n  =  (  1  0  0)  I  os  =2 


The  last  line  in  the  preceding  report  is  reporting  that  the  regions  all_cubes.r  and  center _overlap.r 
are  both  claiming  the  same  volume,  starting  at  (1,  0,  0)  and  continuing  to  do  so  for  2  mm  per  the 
LOS  thickness.  If  the  direction  and  origin  are  changed  to  shoot  along  the  z  axis: 


nirt>  dir  0  0  -1 
n  i  r  t  >  s 

Origin  (x  y  z)  =  (0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  7.4  8  3  3  1  4  7  7  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  -  1.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  9  0.0  0  0  0  0  0  0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obliq_in  Attrib 

cent  e r  _ o v e r  I  ap.  r  (  0.0  0  0  0  0.0  0  0  0  2.0  0  0  0  )  1.0  0  0  0  0.0  0  0  0 

OVERLAP:  ‘c  e  n  t  e  r  _  o  v  e  r  I  a  p .  r  ’  and  ‘a  I  I  _  c  u  bes .  r  ’  xyz_in=(0  0  1)  I  o  s  =2 
a  I  I  _  c  u  bes .  r  "  (  0.0  0  0  0  "o.  0  0  0  0  1.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 

cent  e r  _ o v e r  I  ap.  r  (  0.0  0  0  0  0.0  0  0  0  -  1.0  0  0  0  )  1.0  0  0  0  0.0  0  0  0 

n  i  r  t  > 


Along  that  vector,  center _overlap.r  is  encountered  first,  then  all_cubes.r  intersecting  with 
center _overlap.  r* 

It  should  be  pointed  out  that  overlaps  are  usually  regarded  as  modeling  errors  and  need  to  be 
corrected  unless  they  are  below  some  previously  established  threshold  for  precision  in  the  model. 
One  of  the  potential  uses  of  NIRT  is  to  provide  detailed  information  on  which  regions  are 
overlapping  and  where,  although  tools  such  as  rtcheck  typically  provide  more  comprehensive 
summaries  of  overlap  problems. 


3.  Graphical  Visualization:  NIRT  in  MGED 


The  command  line  interaction  provided  by  NIRT  has  few  options  for  graphic  visualization,  but 
MGED  allows  the  use  and  visualization  of  NIRT  rays.  MGED  provides  a  nirt  command,  but 
rather  than  starting  an  interactive  environment,  each  invocation  of  the  MGED  nirt  command 
casts  one  ray  and  returns  a  report,  together  with  information  allowing  MGED  to  graphically  plot 
the  ray  on  its  wireframe  view. 


*The  last  two  lines  that  appear  in  the  output  when  the  direction  vector  is  changed  are  a  result  of  how  the  raytracing  library 
keeps  track  of  regions  internally.  Even  when  in  an  overlap,  the  ray  is  considered  to  be  in  only  one  region  at  a  time.  In  this 
particular  overlap  situation,  it  might  be  either  region,  so  iibrt  selects  the  region  with  the  lowest  bit  number  (for  more  information, 
see  rt  defoverlap  in  librt/bool.c).  If  the  ray  happens  to  exit  the  lowest  bit  number  region  when  it  exits  the  overlap,  the  active 
region  changes  again  and  another  line  is  generated.  Ultimately,  the  difference  is  inconsequential  and  can  be  disregarded.  Both 
reports  contain  the  key  information:  the  overlap  to  be  removed. 
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3.1  Basic  Usage 


The  most  important  thing  to  remember  when  starting  to  use  NIRT  in  MGED  is  that  the  ray 
direction  is  always  perpendicular  to  the  viewing  plane.  In  other  words,  the  user  is  looking  in  the 
direction  in  which  the  ray  will  be  cast.  There  is  no  option  to  choose  a  different  direction  from 
the  MGED  command  line;  as  a  consequence,  it  may  initially  look  like  nothing  has  happened  in 
the  MGED  wireframe.  The  report  on  the  command  line  will  print  out,  but  the  user  will  have  to 
change  the  direction  from  which  the  model  is  being  viewed  in  MGED  before  the  graphical 
results  will  be  visible. 

Another  important  point  to  remember  about  using  NIRT  in  MGED  is  that  the  user  does  not 
specify  objects  as  arguments  to  the  MGED  nirt  command.  Even  if  supplied  with  objects,  it  will 
not  use  them — the  objects  used  are  those  active  in  MGED’s  wireframe  view. 

For  example,  load  ni  rtexampl  e.  g  in  MGED,  draw  center_cube.r,  set  the  view  direction  to 
a  front  view  looking  down  the  negative  x  axis,  and  run  the  MGED  nirt  command  (figure  2): 

mged>  draw  center_cube.r 
mg  e  d  >  a  e  0  0 
mg  e  d  >  nirt 

Firing  from  view  center... 


Origin  ( x  y  z )  = 

(  0.  0  0  0.  0  0  0.  0  0 

)  (h  v  d)  = 

(  0.  0  0  0.  0  0  0.  0  0  ) 

Direction  ( x  y  z ) 

=  ( -  1.  0  0  0  0  -  0. 

0  0  0  0  0.0  0  0  0  ) 

(az  el)  =  (0.00 

-  0. 

00) 

Region  N  a  me 

En 

try  ( x  y  z) 

LOS 

Obi 

i  q  i  n 

cent  er_cube.  r 

(  1.000 

0.  000 

0.0  0  0  )  2.0  0 

0.000 

mged  > 


Figure  2.  View  of  wireframe  immediately 

after  running  NIRT  within  MGED. 
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Select  the  MGED  view  window  and  press  “3”  to  view  the  path  of  the  ray  (figure  3). 


Figure  3.  View  of  wireframe  after 
changing  view  direction, 
showing  path  of  NIRT  ray. 


Because  the  ray  encountered  only  a  single  region,  the  only  visible  path  drawn  is  the  intersection 
path  of  the  ray  and  the  region  (the  light  blue  line).  The  region  intersection  was  backed  out  to  the 
first  intersection  with  that  region,  despite  the  origination  point  of  the  ray  being  at  the  center  of 
the  sphere. 

Note:  When  a  miss  is  reported  by  NIRT,  no  line  is  drawn  in  the  wireframe  view. 

3.2  Backing  Out  With  NIRT  in  MGED 

Because  NIRT’s  interactive  mode  cannot  be  used  while  in  MGED,  the  b  flag  must  be  provided  to 
the  invocation  of  the  MGED  nirt  command  to  back  out  the  origination  point  while  using  NIRT 
within  MGED.  For  comparison  purposes,  it  is  more  instructive  to  examine 
left_and_right_cubes.r  than  center _cube.r.  To  generate  a  “no  backout”  control  view,  the  display 
is  cleared,  left_and_right_cubes.r  is  drawn,  the  view  direction  is  set,  NIRT  (no  b  flag)  is  run,  and 
the  view  is  switched  to  view  the  ray  path  (figure  4): 


mged>  B  left_and_right_cubes.r 
mged>  ae  0  0 
mg  e  d  >  nirt 


Fi  r 

i  n  g  f  r  o  m  v  i  e  w 

center 

Ori 

gi  n  ( x  y  z)  = 

( 0.  00 

0.  00  0.  00)  ( h  v  d)  = 

( 0.  00  0. 

00  0.  00) 

Di  r 

ec  t i  o  n  ( x  y  z ) 

=  (-  1 

.  0  0  0  0  -  0.  0  0  0  0  0.  0  0  0  0) 

( az  el  ) 

=  (0.00 

-  0. 

00) 

Region  N  a  me 

Entry  ( x  y  z ) 

LOS 

Obi 

i  q  i  n 

r  eg 

i  o  n  1 .  r 

( 

-300.000  0.000 

0.  000) 

100.  00 

0.000 

mge 

d>  ae  90  0 

mge 

d  > 
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Figure  4.  View  of  NIRT  ray  intersecting 

left_and_right_cubes.r  with  ray  origin  at  the 
global  origin. 


The  ray  did  indeed  intersect  a  solid  area  as  indicated  in  the  report  but  only  in  one  of  the  two 
cubes  making  up  the  region.  Repeating  the  steps  using  the  b  flag  to  back  the  origination  point 
out  produces  somewhat  different  results  (figure  5): 


mg  e  d  >  a  e  0  0 
mg  e  d  >  n  i  r  t  -  b 

Firing  from  view  center... 

Origin  (x  y  z)  =  (  6.6  3  0.0  0  0.0  0  )  (h  v  d)  =  (  0.0  0  0.0  0  0.0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  -  0.0  0  0  0  0.0  0  0  0  )  (az  el)  =  (  0.0  0  -  0.0  0  ) 
Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n 

left  and  right  cubes. r  (  3.0  0  0  0.0  0  0  0.0  0  0  )  2.0  0  0.0  0  0 

I  eft_and_ri  ght_cubes.  r  (  -  1.0  0  0  0.0  0  0  0.0  0  0  )  2.0  0  0.0  0  0 

mged>  ae  90  0 


Figure  5.  View  of  NIRT  ray  intersecting 

left_and_right_cubes.r  with  ray  origin  backed  out 
of  the  region. 


Notice  that  the  ray  path  is  now  drawn  over  a  much  larger  area  and  multiple  colors  are  used.  The 
colors  have  significance;  the  purple  segment  in  the  NIRT  ray  path  corresponds  to  the  empty  area 
or  “gap”  between  the  two  solid  areas. 

3.3  Ray  Segment  Coloring  With  NIRT  and  MGED 

NIRT  uses  colors  to  visually  represent  the  information  seen  in  text  form  in  its  report  (table  3). 

To  illustrate  these  outputs,  a  series  of  cube  configurations  will  be  examined.  First,  all  three  are 
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Table  3.  Ray  segment  coloring  conventions. 


Property 

Color 

Solid 

Alternates  between  blue  and  yellow 

Gap 

Purple 

Overlap 

White 

drawn  at  once,  the  viewing  direction  is  set  to  the  -x  direction,  nirt  -b  is  run,  and  the  view  is 
changed  to  see  the  results  (figure  6): 


mged>  B  left_cube.r  center_cube.r  right_cube.r 
mged>  ae  0  0 
mg  e  d  >  n  i  r  t  -  b 

Firing  from  view  center... 


Origin  ( x  y  z )  = 

(  6.  6  3  0.  0  0  0.  0  0)  ( 

h  v  d)  = 

(  0.  00  0. 

00  0.  00) 

Direction  ( x  y  z ) 

=  ( -  1.  0  0  0  0  -  0.  0  0  0  0 

0.  0000) 

( az  el  ) 

=  (0.00 

-  0.  00 

) 

Region  N  a  me 

Entry 

( x  y  z) 

LOS 

Obi  i  q 

i  n 

ri  ght_cube.  r 

(  3.000 

0.  000 

0.  000) 

2.  00 

0. 

000 

cent  er_cube.  r 

(  1.000 

0.  000 

0.  000) 

2.  00 

0. 

000 

1  ef  t  _  c  u  be .  r 

(  -1.000 

0.  000 

0.  000) 

2.  00 

0. 

000 

mged>  ae  90  0 


Figure  6.  Side  view  of  aligned  individual  arb8  cubes  with  a 
single  NIRT  ray  passing  through  all  three  cubes. 

There  are  three  regions  present  according  to  the  text  report.  The  first  region  encountered  is  that 
associated  with  right_cube.r,  and  the  portion  of  the  ray  intersection  in  that  region  is  light  blue. 
The  second  region,  center _cube.r,  has  its  intersection  with  the  yellow  ray.  Note  the  color  of  the 
intersection  in  left_cube.r  is  the  same  as  that  shown  for  right_cube.r.  It  is  important  to  realize 
that  the  same  intersection  color  in  two  different  areas  does  NOT  imply  that  they  are  the  same 
region,  material,  etc.,  nor  do  different  colors  guarantee  that  noncontiguous  geometric  areas  are  in 
different  regions.  The  color  swap  is  simply  an  aid  when  viewing  two  different  contiguous  solid 
regions  that  would  otherwise  be  indistinguishable  visually.  For  example,  if  all  three  cubes  were 
unioned  into  a  single  region,  the  wireframe  would  look  identical  but  the  region  report  would  be 
very  different.  In  that  case,  there  would  be  only  one  region,  and  only  one  line  color  would  be 
needed  (figure  7).  To  illustrate: 
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mg  e  d  >  B  a  I  I  _  c  u  b  e  s .  r 
mged>  ae  0  0 
mg  e  d  >  n  i  r  t  -b 

Firing  from  view  center... 

Origin  (x  y  z)  =  (6.6  3  0.0  0  0.0  0  )  (h  v  d)  =  (0.0  0  0.0  0  0.0  0) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  -  0.0  0  0  0  0.0  0  0  0  )  (az  el)  =  (0.0  0  -  0.0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n 

a  I  I  _ c  u  bes .  r  (  3.0  0  0  0.0  0  0  0.0  0  0  )  6.0  0  0.0  0  0 

mged>  ae  90  0 


Figure  7.  View  of  wireframe  of  three  arb8  cubes  combined 
into  a  single  region  with  a  NIRT  ray  passing 
through  the  region  on  the  same  path  as  that  used 
for  the  individual  arb8  cubes. 

Without  the  color-changing  mechanism,  the  two  previous  situations  would  have  been  visually 
identical  despite  having  very  different  properties. 

The  other  two  situations  that  result  in  a  color  change  are  gaps  and  overlaps.  A  gap  in  NIRT  is 
any  area  along  the  ray  path  after  a  solid  portion  of  a  region  is  encountered  and  before  the  last 
solid  portion  of  a  region  is  encountered  that  does  not  intersect  a  region.  As  an  illustration, 
casting  the  same  ray  through  just  left_cube.r  and  right _cube.r  results  in  a  gap  where 
center _cube.r  was  in  the  first  example  in  this  section  (figure  8): 


mged>  B  left_cube.r  right_cube.r 
mged>  ae  0  0 
mg  e  d  >  n  i  r  t  -  b 

Firing  from  view  center... 

Origin  (x  y  z)  =  (  6.6  3  0.0  0  0.0  0  )  (h  v  d)  =  (  0.0  0  0.0  0  0.0  0  ) 


Direction  (x  y  z)  =  ( - 

1.  0  0  0  0  -  0.  0  0  0  0 

0.  0000) 

( az  el  ) 

=  (0.00 

-  0.  00) 

Region  N  a  me 

Entry 

( x  y  z) 

LOS 

Obi  i  q  in 

r  i  g  ht  _  c  u  be .  r  ( 

3.  000 

0.  000 

0.  000) 

2.  00 

0.000 

left_cube.r  ( 

-  1.  000 

0.  000 

0.  000) 

2.  00 

0.  000 

mged>  ae  9  0  0 
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Figure  8.  View  of  ray  cast  through  only  left_cube.r  and 
right  cube. r. 

To  illustrate  overlaps,  both  center _cube.r  and  all_cubes.r  are  drawn  at  the  same  time  (figure  9): 

mged>  B  all_cubes.r  center_cube.r 
mg  e  d  >  a  e  0  0 
mg  e  d  >  n  i  r  t  -  b 

Firing  from  view  center... 

Origin  (x  y  z)  =  (  6.6  3  0.0  0  0.0  0  )  (h  v  d)  =  (  0.0  0  0.0  0  0.0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  -  0.0  0  0  0  0.0  0  0  0  )  (az  el)  =  (0.0  0  -  0.0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n 

a  I  I  _ c  u  bes .  r  (  3.0  0  0  0.0  0  0  0.0  0  0  )  6.0  0  0.0  0  0 

OVERLAP:  ‘c  e  n  t  e  r  _  c  u  b  e .  r  ’  and  ‘a  I  I  _  c  u  bes .  r  ’  x  y  z  _  i  n  =(  1  0  0)  I  o  s  =2 

mged>  ae  90  0 


Figure  9.  Example  of  an  overlap  region  in  a  NIRT  ray. 


3.4  Mouse-Based  NIRT  Usage 

In  addition  to  providing  a  nirt  command  on  the  MGED  command  line,  there  is  a  mouse-based 
trigger  that  can  be  used.  In  the  MGED  menu,  selecting  Settings->Mouse  Behavior->Query  Ray 
will  change  the  behavior  of  the  mouse.  Selecting  the  view  window,  placing  the  mouse  at  some 
point  over  the  model,  and  performing  a  click  will  cast  a  ray  in  the  view  direction,  centered  at  the 
point  under  the  mouse  pointer  rather  than  the  view  center. 

For  this  example,  bring  up  left_cube.r,  center_cube.r,  and  right _cube. r: 


mged>  B  left_cube.r  center_cube.r  right_cube.r 
mged  > 
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To  aid  with  aiming,  the  grid  overlay  (figure  10)  is  enabled  from  the  menu:  Settings->Grid- 
>Draw  Grid.  Grid  spacing  is  adjusted  with  Settings->Grid  Spacing->Autosize: 


Figure  10.  Grid  overlay  on  MGED 
wireframe. 


With  the  mouse  behavior  set  to  Query  Ray,  the  following  results  are  from  casting  rays  at 
(approximately)  the  (-2  mm,  0  mm),  (0  mm,  0  mm),  and  (2  mm,  0  mm)  grid  points: 


Firing  f  r  om  ( -  1.  9  9  2  8  3  2,  -  4.0  0  0  0  0  0,  -  0.0  2  8  6  7  4  )... 

Origin  (x  y  z)  =  (-  1.9  9  -  1  0.6  3  -  0.0  3)  (h  v  d)  =  (-  1.9  9  -  0.0  3  4.0  0) 

Direction  (x  y  z)  =  (-  0.0  0  0  0  1.0  0  0  0  0.0  0  0  0  )  (az  el)  =  (-  9  0.0  0  -  0.0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n 

I  ef  t  _  c  u  be .  r  (  -  1.9  9  3  -  1.0  0  0  -  0.0  2  9  )  2.0  0  0.0  0  0 

Fi  ri  ng  from  (  0.  0  1  4  3  3  7,  -  4.0  0  0  0  0  0,  -  0.0  0  0  0  0  0  )... 

Origin  (x  y  z)  =  (0.0  1  -  1  0.6  3  -  0.0  0  )  (h  v  d)  =  (0.0  1  0.0  0  4.0  0) 

Direction  (x  y  z)  =  (-  0.0  0  0  0  1.0  0  0  0  0.0  0  0  0  )  (az  el)  =  (-  9  0.0  0  -  0.0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n 

cent  er_cube.  r  (  0.0  1  4  -  1.0  0  0  0.0  0  0  )  2.0  0  0.0  0  0 

Fi  ri  ng  from  (  2.  0  2  1  5  0  5,  -  4.0  0  0  0  0  0,  -  0.0  2  8  6  7  4  )... 

Origin  (x  y  z)  =  (2.0  2  -  1  0.6  3  -  0.0  3  )  (h  v  d)  =  (2.0  2  -  0.0  3  4.0  0  ) 

Direction  (x  y  z)  =  (-  0.0  0  0  0  1.0  0  0  0  0.0  0  0  0  )  (az  el)  =  (-  9  0.0  0  -  0.0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n 

ri  ght_cube.  r  (  2.0  2  2  -  1.0  0  0  -  0.0  2  9  )  2.0  0  0.0  0  0 


Notice  the  entry  points  are  off  from  the  target  values  by  small  but  significant  amounts.  A  more 
precise  way  to  do  this  analysis  is  to  use  the  “snap  to  grid”  feature.  This  feature  is  enabled  by 
selecting  Modes->Snap  To  Grid.  Repeating  this  ray  casts: 


Fi  ri  ng  from  (-  2.  0  0  0  0  0  0,  -  4.0  0  0  0  0  0,  -  0.0  0  0  0  0  0  )... 

Origin  (x  y  z)  =  (-  2.0  0  -  1  0.6  3  -  0.0  0  )  (h  v  d)  =  (-  2.0  0  0.0  0  4.0  0  ) 
Direction  (x  y  z)  =  (-  0.0  0  0  0  1.0  0  0  0  0.0  0  0  0  )  (az  el)  =  (-  9  0.0  0  -  0.0  0  ) 
Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n 

I  ef  t  _  c  u  be .  r  (  -  2.0  0  0  -  1.0  0  0  0.0  0  0  )  2.0  0  0.0  0  0 


Fi  ri  ng  from  (  0.  0  0  0  0  0  0,  -  4.0  0  0  0  0  0,  -  0.0  0  0  0  0  0  )... 

Or i  gi  n  ( x  y  z)  =  (  0.  0  0  -  1  0.  6  3  -  0.  0  0  )  (  h  v  d)  =  ( -  0.  00 

Direction  (x  y  z)  =  (-  0.0  0  0  0  1.0  0  0  0  0.0  0  0  0  )  (az  el)  = 
Region  Name  Entry(xyz) 

c e nt  e r  _ c  u  be .  r  (  0.0  0  0  -  1.0  0  0  0.0  0  0  ) 


0.  00  4.  00) 

( -  9  0.  0  0  -  0.  0  0  ) 
LOS  Obi  i  q _  i  n 
2.0  0  0.0  0  0 
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Fi  ri  ng  from  (  2.  0  0  0  0  0  0,  -  4.  0  0  0  0  0  0,  -  0.  0  0  0  0  0  0  ).  .  . 

Origin  (x  y  z)  =  (  2.0  0  -  1  0.6  3  -  0.0  0  )  (h  v  d)  =  (  2.0  0  0.0  0  4.0  0  ) 

Direction  (x  y  z)  =  (-  0.0  0  0  0  1.0  0  0  0  0.0  0  0  0)  (az  el)  =  (-  9  0.0  0  -  0.0  0) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n 

ri  ght_cube.  r  (  2.0  0  0  -  1.0  0  0  0.0  0  0  )  2.0  0  0.0  0  0 


These  values  are  exact  thanks  to  the  corrections  provided  by  the  snap  to  grid  mode. 


4.  Configuring  NIRT  With  the  Query  Ray  Control  Panel 


When  using  NIRT  within  MGED,  some  of  its  settings  can  be  changed  through  a  graphical  dialog 
found  in  the  menu:  MGED’s  Tools->Query  Ray  Control  Panel.  This  section  will  describe  the 
basic  options.  More  advanced  settings  will  be  covered  later. 

4.1  Enabling  and  Disabling  Mouse-Based  NIRT  Ray  Casting 

Earlier,  mouse-based  NIRT  ray  casting  was  enabled  via  a  menu  option.  The  Query  Ray  Control 
Panel  offers  a  more  convenient  option  for  toggling  the  same  behavior  via  the  Mouse  Active 
check  box  (figure  1 1)  in  the  lower  left  comer  of  the  dialog  box.  Selecting  this  check  box  and 
clicking  Apply  will  activate  the  mouse  as  a  trigger  for  a  ray  cast.  Clearing  the  Mouse  Active 
check  box  and  clicking  Apply  will  restore  the  default  behavior. 


Query  Ray  Colors 

odd 

0 255  255 

-* 

even 

255  255  0 

'IH 

void 

255 0 255 

B 

overlap 

255  255  255 

1  -ll 

Base  Name  query_ray 

Effects. 

r  Echo  Gmd 

Both  —1 

(r  Mouse  Active  jr  Use  Air 

Advanced... 

OK 

Apply  Reset 

Dismiss 

Figure  11.  MGED’s  Query  Ray  Control  Panel  with 
the  Mouse  Active  check  box  circled. 
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4.2  Customizing  NIRT  Coloring  in  MGED 

Although  the  default  colors  normally  work  well,  it  is  possible  to  adjust  the  colors  used  for 
regions,  overlaps,  and  gaps  via  the  Query  Ray  Control  Panel  (figure  12).  The  odd  and  even 
colors  correspond  to  solid  areas  of  regions,  void  is  a  gap  between  regions,  and  overlap  is  the 
color  for  overlapping  regions.  Select  a  color  by  typing  in  an  RGB  color  designation  directly  or 
using  the  drop-down  menu  visible  on  the  right  end  of  each  color  entry  (figure  13).  If  the  default 
color  listings  are  insufficient,  the  Color  Tool  can  be  used  for  more  fine-tuned  selection  (figure 
14). 


Base  Name  query_ray 


Effects 

Echo  Cmd 

Both  — 

r  Mouse  Active 

T  Use  Air 

Advanced... 

OK  Apply 

Reset 

Dismiss 

Figure  12.  MGED’s  Query  Ray  Control  Panel  with 
the  Query  Ray  Colors  circled. 
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Figure  13.  MGED’s  Query  Ray  Control  Panel  with  an 
example  color  list  selected. 


Figure  14.  MGED’s  color  tool. 

4.3  Customizing  the  Pseudo-Primitive  Base  Name 

MGED  and  NIRT  use  “pseudo”  primitives  to  describe  the  actual  graphical  lines.  They  will  not 
behave  like  “normal”  primitives,  but  they  do  need  a  name.  By  default,  these  names  are  the  string 
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“query_ray”  and  the  color  used  for  the  string.  For  example,  the  pseudo-primitive  list  after 
running  NIRT  on  the  cube  example  (figure  15)  with  a  gap  is  shown  here: 

mged>  who  p 

q u e r y_ r a y f f f f  0 0  q u e r y_ r a y f f f f  q u e r y_ r a y f f 0 Of  f 


Figure  15.  Wireframe  view  of  a  NIRT  ray  using  multiple 
colors. 

This  naming  convention  is  used  almost  completely  as  an  internal  mechanism  by  MGED  and 
NIRT.  For  example,  an  1  command  on  query  jayffff  does  not  work: 

mged>  I  query_rayffff 

rt_db_get_i  nternal (query_rayffff)  fai I  ure 


However,  it  is  possible  to  use  these  names  to  erase  the  NIRT  line  segments  from  the  drawing. 
For  example,  to  remove  the  purple  line  segments  from  the  wireframe,  use  the  command: 


mged>  erase  query_rayffOOff 

This  will  remove  only  the  purple  line  segment  and  leave  the  others  (figure  16). 


Figure  16.  Wireframe  view  of  the  NIRT  ray  after  erasing 
query jayffOOff. 
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The  Query  Ray  Control  Panel  also  offers  a  way  to  customize  the  base  name  used  for  these 
pseudo-primitives  (figure  17).  Changing  the  Base  Name  from  query_ray  to  line_segment  and 
rerunning  NIRT  results  in  pseudo-primitives  named: 

mged>  who  p 

Iine_segmentffff00  line_segmentffff  Iine_segmentff00ff 


odd 

even 

void 

overlap 


Query  Ray  Colors 

0  255  255 

— 1 

255  255  0 

255  0  255 

m 

255  255  255 

- 

3ase  Name  line_segment 


Effects 


r  Echo  Cmd 


Both 


r  Mouse  Active  T  Use  Air  Advanced... 
OK  Apply  Reset 


Dismiss 


Figure  17.  MGED’s  Query  Ray  Control  Panel  showing  a 
new  Base  Name. 


4.4  Echoing  the  Internal  nirt  Command 

The  Echo  Cmd  check  box  in  the  Effects  row  allows  the  user  to  enable/disable  the  printing  of  the 
internal  nirt  command  being  run  by  MGED  (figure  18). 
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odd 

even 

void 

overlap 


Base  Name  query_ray 


Effects  CT  Echo  CrmdQ  Both  — ■ 

r  Mouse  Active  l"~  Use  Air 

Advanced... 

OK  Apply  Reset 

Dismiss 

Figure  18.  MGED’s  Query  Ray  Control  Panel  with  the  Echo 
Cmd  check  box  circled. 


Query  Ray  Colors 


O  255  255 

-- 

255  255  O 

- 

255  O  255 

m 

255  255  255 

For  example,  with  Echo  Cmd  selected,  casting  a  ray  into  the  last  example  in  the  previous  section 
results  in: 


n  i  r  t  -  e  f  mt  r  f  mt  h  f  mt  p  f  mt  m  f  mt  o  f  mt  f  f  mt  g  -  e  f  mt  p 
“%e  %e  %e  %e\  n”x_in  y  _  i  n  z_in  I  os  -e  xyz  4.0  0  0  0  0  0  0.0  2  2  2  2  2  0.  011111;  di  r  -  1.0  0  0  0  0  0 
-0.000000  0.000000;  s  -e  fmt  r  “\  n”;  f  mt  p  f  mt  o  “%e  %e  %e  %e  \  n  ”  o  v  _  x  _  i  n  o  v  _  y  _  i  n 

ov  z  in  ov  I  o  s  -e  xyz  4.0  0  0  0  0  0  0.0  2  2  2  2  2  0.  011111;  di  r  -  1.0  0  0  0  0  0  -  0 .  0  0  0  0  0  0  ~0  .~0  0  0  0  0  o”;  "s 

-e  fmt  r  “\  nOrigin  (x  y  z)  =  (%.  2f  %.  2f  %.  2  f )  (h  v  d)  =  (%.  2f  %.  2f  %.  2f)\  n  Di  recti  on 

( x  y  z )  =  (  %.  4  f  %.  4  f  %.  4  f )  ( a  z  el)  =  (  %.  2  f  %.  2  f )  \  n  ”  x  _  o  r  i  g  y  _  o  r  i  g  z  _  o  r  i  g  h  v  d  _  o  r  i  g 

x_diry_dirz_dirae-efmth“  Region  Name  Entry(xyz) 

LOS"  Ob  I  i  q_  i  n\  n”;  fmt  p  “%-20s  (%9.3f  %9.3f  %9.3f)  %8.2f  %8.3f\  n”reg_name  x_in 
y  _  i  n  z_in  los  obi  i  q  _  i  n ;  fmt  f  fmt  m  “You  missed  the  tar  get  \  n”;  fmt  o  “OVERLAP: 

’%s  ’  and  ‘%s  ’  xyz_  i  n  =(  %g  %g  %g)  I  o  s  =  %g  \  n”  ov_regl_name  ov_reg2_name  ov_x_in  ov_y_in 
o  v  _  z  _  i  n  o  v_  I  os;  "f  mt  g  “”  -  e  xyz  4.0  0  0  0  0  0  0.  0~2  2  2  2  2~  0 .  0 1 1 1 1~1 ;  d  i  r"  -  1 .  0  0  0  0~0  o"  -  0 .  0  0~0  0~0  0 
0.000000;  s  -b  nirt_example.g  right_cube.r  center_cube.r  left_cube.r 


Fi  ri  ng  from  (  4.  0  0  0  0  0  0,  0.  0  2  2  2  2  2,  0.  0  1  1  1  1  1  ).  .  . 

Origin  (x  y  z)  =  (1  0.6  3  0.0  2  0.0  1  )  (h  v  d)  =  (0.0  2  0.0  1  4.0  0) 
Direction  (x  y  z)  =  (-  1.0  0  0  0  -  0.0  0  0  0  0.0  0  0  0  )  (az  el)  =  (  0.0  0  -  0.0  0  ) 


Region  N  a  me 

Entry 

(xyz) 

LOS 

Obi  i  q  in 

r  i  ght_cube.  r 

(  3.000 

0.  022 

0.  Oil) 

2.  00 

0.  000 

c  e  nt  e  r  _  c  u  be .  r 

(  1.000 

0.  022 

0.  Oil) 

2.  00 

0.  000 

1  ef  t  _  c  u  be .  r 

(  -1.000 

0.  022 

0.  Oil) 

2.  00 

0.  000 

This  feature  is  primarily  useful  for  debugging  or  scripting  outside  of  MGED.  Additional 
information  regarding  debugging  in  NIRT  can  be  found  in  appendix  A. 
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4.5  Selecting  Graphical  and  Textual  Output 


By  default,  NIRT  in  MGED  outputs  both  graphical  and  text-based  output.  This  is  reflected  in  the 
drop-down  menu  on  the  right  side  of  the  Effects  row  in  the  Query  Ray  Control  Panel,  which  is 
set  to  Both  (figure  19).  The  other  options  in  the  drop-down  menu  allow  the  user  to  specify  only 
Graphics  (no  text  report  is  printed)  or  only  Text  (no  ray  path  is  drawn  in  the  wireframe). 


Query  Ray  Colors 

odd 

0  255  25S 

— i j  i: 

even 

255  25S  0 

void 

255  0  255 

B 

OV^diip 

255  25.S255 

-  1 

Base  Maine  query  ray 


Effects 

Echo  and 

Both  — ■ 

i 

Text 

1 

Mouse-  Active 

1”  Use  Air 

Ad- 

Graphics 
*  Both 

QK  Apply 

Reset 

Dismiss 

Figure  19.  MGED’s  Query  Ray  Control  Panel 
with  the  Effects  drop-down  menu 
shown. 


5.  Reporting  Options 


Up  until  this  point,  only  the  default  output  configuration  of  NIRT  has  been  used.  Much  of  the 
power  of  NIRT  comes  from  taking  that  output  and  changing  the  format  and  information  to 
supply  precisely  what  is  needed  for  any  given  purpose. 

5.1  How  to  Change  the  Reporting  Format 

The / option  allows  NIRT  to  load  customized  formatting  files  that  change  its  reporting  style.  In 
addition  to  the  default  style  used  thus  far  in  this  report,  NIRT  has  several  built-in  options  for 
convenient  formatting.  Running  nirt  -L  prints  out  a  list  of  available  built-in  formats  with  a 
description  of  each: 


21 


user  @ma  chine  ~  $  nirt  -L 

csv-gap  -  Comma  Separated  Value  Output  Formatting  with  Gap  Reporting 

entryexit  -  Variation  on  Standard  format  that  prints  Entry  and  Exit  points  rather  than  LOS. 

csv  -  Comma  Separated  Value  Output  Formatting 

g a p 2  -  Reporting  with  Gap  input  point,  output  point  and  LOS 

gapl  -  Reporting  with  Gap  Input  Point  and  LOS 

default  -  Standard  NIRT  Reporting  Format 


To  use  a  particular  format,  the  name  on  the  left  (csv,  gapl,  etc.)  is  supplied  as  an  argument  to  the 
/flag. 

For  example,  cases  where  data  needs  to  be  imported  into  a  spreadsheet  can  benefit  from  using 
comma-separated- variable  (csv)  output  formatting.  The  individual  cube  regions  are  loaded  and  a 
ray  cast: 


user  @ma  chine  ~  $  nirt  -b  -f  csv  nirt_example.g  left_cube.r  center_cube.r  right_cube.r 
BRL-CAD  Release  7.13.0  Natalie’s  Interactive  Ray  Tracer 
Tue,  26  Aug  2008  23:21:32  -  0400,  Compilation  2 
u  s  e  r  @1  o  c  a  I  h  o  s  t  :  /  u  s  r  /  b  r  I  c  a  d 
Database  file:  ‘n  i  r  t  _  ex  a  mp  I  e .  g  ’ 

Building  the  directory... 

Get  trees... 

Prepping  the  geo  me  try... 

Objects  ‘I  ef  t  _  c  u  be .  r  ’  ‘c  e  nt  e  r  _  c  u  be .  r  ’  ‘r  i  g  ht  _  c  u  be .  r  ’  processed 
Database  title:  ‘Example  BRL-CAD  Database’ 

Database  units:  ‘mm’ 

mo  d  e  I  _  mi  n  =  (  -  3 ,  -1,  -1)  mo  d  e  I  _  ma  x  =  (  3 ,  1,  1) 
n  i  r  t  >  s 
Ray : 

x  _  o  r  i  g,  y_ori  g,  z_ori  g,  d_ori  g,  h, v, x  _  d i  r, y_di  r,  z_di  r,  az,  el 

6~  6  3  3  2  4  9  5  8,  0.  0  0  0  0  0  0  0  0,  0.  0  0  0  0  0  0  0  0,  0.  0  0  0  0  0  0  0  0,  0  ~  0  0  0  0  0  0  0  0,  0.  0  0  0  0  0  0  0  0,  -  1.  0  0  0  0  0  0  0  0,  0.  0  0  0  0  0  0.  .  . 

Res  u I  t  s : 

r  e  g  _  n  a  me ,  pat  h_name,  reg_i  d,  x_i  n,  y_i  n,  z_i  n,  d_i  n,  x  _  o  u  t ,  y  _  o  u  t ,  z  _  o  u  t ,  d_out,  I  os,  seal  e  d  _  I  os,  o.  .  . 

”ri  g ht  c  u  be .  r  ”,  ”/  r  i  g  ht  "cube.'r  ”,  1  0  0  2,  3.  0  0  0  0  0  0,  0.  0  0  0  0  0  0,  0.  0  0  0  0  0  0,  3.  0  0  0  0  0  0,  1.  0  0  0  0  0  0,  0.  0  0  0.  .  . 

’’center  cube,  r  ”,  ’’/center  cube,  r  ”,  1  0  0  0,  1.  0  0  0  0  0  0,  0.  0  0  0  0  0  0,  0.  0  0  0  0  0  0,  1.  0  0  0  0  0  0,  -  1.  0  0  0  0  0  0,  0  _ 

’’left  cube,  r  I  eft  c  u  be .  r  ”,  1  0  0  1 ,  -  1 .  0  0  0  0  0  0 ,  0 .  0  0  0  0  0  0 ,  0 .  0  0  0  0  0  0 ,  -  1 .  0  0  0  0  0  0 ,  -  3 .  0  0  0  0  0  0 ,  0 .  0  0 .  .  . 


The  output  of  the  s  command  is  then  copied  to  a  file  (for  example,  test.csv)  and  imported  into  a 
spreadsheet  (figure  20). 

Since  copying  to  a  file  is  impractical  in  many  cases,  NIRT  provides  an  interactive  command 
called  dest  which  can  specify  an  output  file.  In  the  previous  case,  the  test.csv  file  is  created 
easily: 


nirt>  dest  test.csv 
n  i  r  t  >  s 
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Figure  20.  Shot  command  output  file  imported  into  a  spreadsheet. 


The  file  contents  match  the  previous  output: 


Ray : 

x_or  i  g,  y  _  o  r  i  g,  z  _  o  r  i  g,  d  _  o  r  i  g,  h,  v,  x  _  d  i  r,  y  _  d  i  r ,  z  _  d  i  r ,  az,  el 

6"  6  3  3  2  4  9  5  8,  0.  0  0  0  0  0  0  0  0,  0.  0  0  0  0  0  0  0  0,  0.  0  0  0  0  0  0  0  0,  (f  0  0  0  0  0  0  0  0,  0.  0  0  0  0  0  0  0  0,  -  1.  0  0  0  0  0  0  0  0,  0.  0  0  0  0  0  0.  .  . 

Res  u I  t  s : 

r  e  g  _  n  a  me ,  pat  h_name,  reg_i  d,  x_i  n,  y_i  n,  z_i  n,  d_i  n, x_out, y  _  o  u  t ,  z  _  o  u  t ,  d  _  o  u  t , I  os,  seal  e  d  _ I  os,  o.  .  . 

“ri  g  h t  _  c  u  be .  r  ”,  “/ r  i  g  ht  _"c  u  be .  ~r  ”,  1  0  0  2,  3.  0  0  0  0  0  0,  0.  0  0  0  0  0  0,  0.  0  0  0  0  0  0,  3.  0  0  0  0  0  0,  1.  0  0  0  0  0  0,  0.  0  0  0.  .  . 

“cent  er_cube.  r  ”,  “/  c  e  n  t  e  r  _  c  u  b  e .  r  ”,  1000,  1.  000000,  0.  000000,  0.  000000,  1.  000000,  -1.  000000,  0.  .  .  . 
i  eft  _  cube,  r  ”,  “/  I  ef  t_cube.  r”,  1001,  -  1.  000000,  0.  000000,  0.  000000,  -  1.  000000,  -  3.  000000,  0.  00.  .  . 


To  restore  output  to  the  command  line,  use  dest  default  to  redirect  to  standard  output: 


ni  r  t  >  dest  default 


When  dealing  with  spaces  between  models,  it  is  sometimes  advantageous  to  report  gaps  in 
NIRT’s  output.  MGED’s  visualization  routines  show  gaps  between  regions  as  purple  lines,  but 
the  default  text  report  does  not  include  information  about  gaps.  Sometimes  it  is  desirable  to  get 
exact  information  on  gaps,  particularly  when  they  represent  errors  in  a  model.  The  gapl  and 
gap2  formats  will  include  information  about  gaps.  Running  NIRT  on  the  left_and_right_cubes.r 
object  with  backout  enabled  provides  an  example: 


user  @ma  chine  ~  $  nirt  -b  -f  g  a  p  2  ni  rt_exampl  e.  g  left_and_right_cubes.r 
BRL-CAD  Release  7.13.0  Natalie’s  Interactive  Ray  Tracer 
Tue,  26  Aug  2008  23:21:32  -  0400,  Compilation  2 
user@l  ocal  host:/usr/brl  cad 
Database  file:  ‘n  i  r  t  _  exa  mp I  e .  g  ’ 

Building  the  directory... 

Get  trees... 
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Prepping  the  geo  me  try... 

Object  ‘I  ef  t  _  a  nd_  r  i  g  ht  _  c  u  bes .  r  ’  processed 
Database  title:  ‘Example  BRL-CAD  Database’ 

Da  t  a  ba  s  e  units:  ‘mm’ 

mo  d  e  I  _  mi  n  =  (  -  3 ,  -1,  -1)  mo  d  e  I  _  ma  x  =  (  3 ,  1,  1) 
n  i  r  t  >  s 

Origin  (x  y  z)  =  (  6.6  3  3  2  4  9  5  8  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h 
Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 
Region  Name  Entry(xyz) 

I  ef  t  _ a  nd_  r  i  g  ht  _ c  u  bes .  r  (  3.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

GAP:  x  y  z  _  i  n  =  (  1  0  0)  xyz_out=(-l  0  0)  I  o  s  =  2 
I  ef  t  _ a  nd_  r  i  g  ht  _ c  u  bes .  r  (  -  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 


v  d)  =  ( 0.  0000  0.  0000  0.  0000) 

( az  el )  =  ( 0.  00000000  0.  00000000) 
LOS  Obi i  q _ i  n  At  t  r i  b 
2.0000  0"0000 

2.0  0  0  0  0.0  0  0  0 


5.2  Handling  Attribute  Reporting 

The  default  command  line  reporting  format  lists  an  Attrib  column  where  attributes  may  be 
printed  but  does  not  print  any  as  default  output.  Including  attributes  in  a  NIRT  report  requires 
adding  attributes  in  question  to  the  attributes  table  using  the  attr  command.  For  example,  if  the 
user  wants  the  report  to  identify  the  rgb  color  being  used  for  each  region: 

user  @ma  chine  ~  $  nirt  -b  nirt_example.g  I  eft_cube_col  or.  r  center_cube_color.r  ri  ght_cube_col  or.  r 
n  i  r  t  >  attr  rgb 
n  i  r  t  >  attr  -  p 
”r  g  b  ” 
n  i  r  t  >  s 


Get  trees... 

Prepping  the  geo  me  try... 

Objects  ‘I  ef  t  _  c  u  be_  c  o  I  o  r .  r  ’  ‘c  e  nt  e  r  _  c  u  be_  c  o  I  o  r .  r  ’  ‘r  i  g  ht  _  c  u  be_  c  o  I  o  r .  r  ’  processed 
Origin  (x  y  z")  =  ("6.6  3  3  2  4  9  5  8  0.  00  0”0  000  0"  0.  00000000)  ("h  v  d")  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 
Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  Attrib 


r  i  g  ht  _  c  u  be_  c  o 1  or.  r 

(  3.0  0  0  0 

0.  0  0  0  0 

0.  0000) 

2.  0000 

0.  0000 

r  g  b  =2  5  5  /  0  /  0 

cent  er_cube_col  or.  r 

(  1.0  0  0  0 

0.  0  0  0  0 

0.  0000) 

2.  0000 

0.  0000 

r  g  b  =0  /  2  5  5  / 0 

1  eft_cube_col  or.  r 

(  -1.0000 

0.  0  0  0  0 

0.  0000) 

2.  0000 

0.  0000 

r  g  b  =0/  0/255 

Notice  how  the  report  now  includes  the  rgb  attribute  for  each  region.  The  p  flag  prints  the 
current  list  of  attributes  to  include.  In  the  previous  case,  it’s  simply  the  “rgb”  attribute.  An / 
option  can  be  supplied  to  flush  all  entries  and  clear  the  table. 


n  i  r  t  >  attr  -  f 
n  i  r  t  >  attr  -p 


Multiple  attributes  can  also  be  specified: 


nirt>  attr  rgb  region 
n  i  r  t  >  attr  -  p 
”r  g  b  ” 

”r  e  g  i  on” 
n  i  r  t  >  s 

Get  trees... 

Prepping  the  geo  me  try... 

Objects  ‘I  ef  t  _  c  u  be_  c  o  I  o  r .  r  ’  ‘c  e  nt  e  r  _  c  u  be_  c  o  I  o  r .  r  ’  ‘r  i  g  ht  _  c  u  be_  c  o  I  o  r .  r  ’  processed 
Origin  (x  y  z")  =  ("6.6  3  3  2  4  9  5  8  0.  00  0~0  000  0"  0.  00000000)  ("h  v  d")  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 
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Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 


Re g i  on 

Na  me 

Entry 

( x  y  z) 

LOS 

Obi  i  q  in 

At  t  r  i  b 

r  i  g  ht  _  c  u  be_ 

col  or.  r 

(  3.0  0  0  0 

0.  0  0  0  0 

0.  0000) 

2.  0000 

0.  0000 

r  g  b  =2  5  5  /  0  /  0 

r  eg i  o n  =  R 

c  e  nt  e  r  _  c  u  be 

_  c  o 1  or.  r 

(  1.0  0  0  0 

0.  0  0  0  0 

0.  0000) 

2.  0000 

0.  0000 

r  g  b  =0  /  2  5  5  / 0 

r  eg i  o n  =  R 

1  ef  t  _  c  u  be_  c  o  1  or.  r 

(  -1.0000 

0.  0  0  0  0 

0.  0000) 

2.  0000 

0.  0000 

r  g  b  =0/  0/255 

r  eg i  o n  =  R 

If  the  user  wishes  to  add  yet  another  attribute,  it  could  be  appended  to  the  current  list  with 
another  attr  command. 

To  provide  attributes  to  the  list  on  startup,  the  A  option  will  add  its  arguments  to  the  list: 


user  @ma  chine  ~  $  nirt  -b  -  A  rgb  nirt_example.g  I  eft_cube_col  or.  r  center_cube_color.r 
r  i  g  ht  _  c  u  be_  c  o I  or.  r 

BRL-CAD  Release  7.13.0  Natalie’s  Interactive  Ray  Tracer 
Mon,  25  Aug  2  0  0  8  1  5:1  4:0  3  -  0  4  0  0,  Compilation  1 
u  s  e  r  @1  o  c  a  I  h  o  s  t  :  /  u  s  r  /  b  r  I  c  a  d 
Database  file:  ‘n  i  r  t  _  ex  a  mp  I  e .  g  ’ 

Building  the  directory... 

Get  trees... 

Prepping  the  geo  me  try... 

Objects  ‘I  ef  t  _  c  u  be_  c  o  I  o  r .  r  ’  ‘c  e  nt  e  r  _  c  u  be_  c  o  I  o  r .  r  ’  ‘r  i  g  ht  _ c  u  be_ c  o I  o r .  r  ’  processed 
Database  title:  ‘Example  BRL-CAD  Database’ 

Database  units:  ‘mm’ 

mo  d  e  I  _  mi  n  =  ( -  3 ,  -1,  -1)  mo  d  e  I  _  ma  x  =  (  3 ,  1,  1) 
n  i  r  t  >  s 

Origin  (x  y  z)  =  (  6.6  3  3  2  4  9  5  8  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0)  (az  el)  =  (0.0  0  0  0  0  0  0  0  0.0  0  0  0  0. 


Region  N  a  me 

Entry 

( x  y  z) 

LOS 

Obi  i  q  in 

Attrib 

r  i  g  ht  _  c  u  be_  c  o  1  or.  r 

(  3.0  0  0  0 

0.  0  0  0  0 

0.  0000) 

2.  0000 

0.  0000 

r  g  b  =2  5  5  /  0  /  0 

cent  er_cube_col  or.  r 

(  1.0  0  0  0 

0.  0  0  0  0 

0.  0000) 

2.  0000 

0.  0000 

r  g  b  =0  /  2  5  5  / 0 

1  eft_cube_col  or.  r 

(  -1.0000 

0.  0  0  0  0 

0.  0000) 

2.  0000 

0.  0000 

r  g  b  =0/  0/255 

Note:  Reporting  attributes  when  running  NIRT  from  within  MGED  is  more  involved.  This  will 
be  covered  later. 

5.3  Changing  Units 

By  default,  NIRT’s  interactive  command  line  mode  reads  and  writes  all  dimensions  in 
millimeters,  regardless  of  the  units  set  in  the  geometry  file.  This  is  configurable  via  the  units 
command,  which  will  accept  mm,  cm,  m,  in,  and  ft  as  arguments  or  print  the  current  unit  with  no 
arguments.  Using  center_cube.r  as  an  example: 


n  i  r  t  >  units 
units  =  ‘mm’ 
n  i  r  t  >  s 

Origin  (x  y  z)  =  (  3.4  6  4  1  0  1  6  2  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0)  (az  el)  =  (0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obliq_in  Attrib 

cent  er_cube.  r  (  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 

n  i  r  t  >  units  m 
n  i  r  t  >  s 

Origin  (x  y  z)  =  (  0.0  0  3  4  6  4  1  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0)  (az  el)  =  (0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  Attrib 
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cent  er_cube.  r  (  0.0  0  1  0  0.0  0  0  0  0.0  0  0  0  )  0.0  0  2  0  0.0  0  0  0 

nirt>  units  in 
n  i  r  t  >  s 

Origin  (x  y  z)  =  (  0.1  3  6  3  8  1  9  5  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  At  t  r  i  b 

cent  er_cube.  r  (  0.0  3  9  4  0.0  0  0  0  0.0  0  0  0  )  0.0  7  8  7  0.0  0  0  0 

nirt>  units  ft 
n  i  r  t  >  s 

Origin  (x  y  z)  =  (  0.0  1  1  3  6  5  1  6  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  At  t  r  i  b 

cent  er_cube.  r  (  0.0  0  3  3  0.0  0  0  0  0.0  0  0  0  )  0.0  0  6  6  0.0  0  0  0 


When  run  from  within  MGED,  NIRT  uses  the  current  units  set  within  the  MGED  environment. 


6.  Other  Options 


6.1  Silent  and  Verbose  Modes 

NIRT  supports  two  behaviors  associated  with  output  verbosity.  The  interactive  command  line 
environment  uses  the  verbose  mode  by  default.  Verbose  mode  prints  out  the  headers  containing 
information  about  the  BRL-CAD  version  number,  database  name,  database  title,  etc.,  and  also 
provides  the  “nirt>”  command  prompt  label.  Silent  mode  used  by  default  inside  the  MGED 
command  window  does  not  print  any  headers  or  prompt  label. 

When  generating  large  numbers  of  results,  it  is  sometimes  desirable  to  switch  to  silent  mode  on 
the  command  line.  This  is  accomplished  by  supplying  the  s  option  to  nirt.  Similarly,  in  the 
MGED  window,  supplying  the  v  option  will  produce  the  full  text  output  of  NIRT’ s  interactive 
mode  in  the  MGED  window. 

6.2  Using  Air  Regions 

Air  regions  have  a  special  status  in  BRL-CAD,  and  by  default,  NIRT  does  not  report  them.  If 
the  user  does  wish  to  have  air  regions  reported,  the  u  option  is  supplied  with  an  argument  of  1  to 
activate  air  region  reporting.  This  is  illustrated  with  a  center _cube_air.r  object: 


user  @ma  chine  $  nirt  -s  -b  -uO-f  g  a  p  2  nirt_example.g  left_and_right_cubes.r  center_cube_air.r 
s 

Origin  (x  y  z)  =  (6.6  3  3  2  4  9  5  8  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0)  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  At  t  r  i  b 

I  ef  t  _  a  n  d  _  r  i  ght  _cubes .  r  (  3.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0  "  0  0  0  0 

GAP:  x  y  z  _  i  n  =  (  1  0  0)  xyz_out=(-l  0  0)  I  o  s  =  2 

I  ef  t_and~ri  ght_cubes.  r  (  -  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0)  2.0  0  0  0  0.0  0  0  0 


user  @ma  chine  $  nirt  -s  -b  -ul-f  g  a  p  2  nirt_example.g  left_and_right_cubes.r  center_cube_air.r 
s 
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Origin  (x  y  z)  =  (  6.6  3  3  2  4  9  5  8  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  At  t  r  i  b 

I  eft_and_ri  ght_cubes.  r  (  3.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  o7  0  0  0  0 

center  cube  air.r  (  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 

I  eft_and_ri  ght_cubes.  r  (  -  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0)  2.0  0  0  0  0.0  0  0  0 

In  the  first  case,  area  in  between  the  cubes  of  left_and_right_cubes.r  is  reported  as  a  gap  when 
gap  reporting  is  enabled.  In  the  second  case,  center  cube _air.r  is  treated  as  a  region,  and  a  new 
region  report  line  is  generated  instead  of  a  gap  report. 


The  Query  Ray  Control  Panel  also  offers  a  way  to  select  the  Use  Air  option  (figure  21): 


Base  Name  query_ray 


Effects  Echo  Cmd  Both  — < 

Mouse  Active  ^  Use  Ain 

Advanced... 

OK  Apply  Reset 

Dismiss 

Figure  21.  MGED’s  Query  Ray  Control  Panel  showing  the 
Use  Air  check  box. 


6.3  Reading  an  Orientation  Matrix  and  Commands 

This  option  is  seldom  used  manually  from  the  command  line.  Its  primary  purpose  is  to  allow 
MGED’s  saveview  command  to  generate  scripts  that  allow  commands  run  on  MGED  views  to 
be  repeated  on  the  command  line.  By  default,  the  saveview  MGED  command  generates  scripts 
to  run  rt,  so  it  is  necessary  to  specify  nirt  with  saveview’s  e  option;  for  example,  saveview  -e 
nirt  tsv.script.  Typically,  the  saveview  MGED  command  generates  scripts  with  a  few  other 
options  included,  but  the  important  parts  are  the  orientation  matrix  and  eyepoint: 


27 


#!  /  b  i  n /  s  h 

nirt  -M  ni  rt_exampl  e.  g  ‘r  i  g  ht  _  c  u  be .  r  ’  ‘c  e  nt  e  r  _  c  u  be .  r  ’  ‘I  ef  t  _  c  u  be .  r  ’  <  <  E  0  F 

orientation  2~  4  8  0  9  7  3  4  9  0  4  5  8  7  2  7  e~-  0  1  4 .  7  6  5  9  0  5  7  3  2~6  6  0  4  8  5  e  -  0 1  7.  4  8  0  9  7  3  4  9  0  4  5  8  7  2  9  e  -  01  \ 
3.  894348305183902e- 01; 

eye  pt  6.  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  e +0  0  4 .  2  0  1  2  4  5  2  2  9  2  5  8  2  6  2  e +0  0  3 .  4  1  5  5  3  9  2  3  7  7  2  2  9  1  9  e +0 0 ; 


When  this  script  is  run,  a  NIRT  report  is  generated  for  a  ray  cast  in  the  same  direction  as  that 
which  would  have  been  cast  in  the  original  MGED  view  where  the  saveview  command  was  run: 


ma  chine:-  u  s  e  r  $  sh  tsv. script 

Origin  (x  y  z)  =  (6.0  0  0  0  0  0  0  0  4.2  0  1  2  4  5  2  3  3.4  1  5  5  3  9  2  4  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  8.0  8  1  9  ) 

Direction  (x  y  z)  =  (-  0.7  4  2  4  0  3  8  8  -  0.5  1  9  8  3  6  7  9  -  0.4  2  2  6  1  8  2  6  )  (az  el)  =  (  3  5.0  0  0  0  0  0  0  0  2  5.0  0  0  0  0  0  0  0  ) 
Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  At  t  r  i  b 


ri  ght_cube.  r 

(  1.4  2  8  1 

1.  0  0  0  0 

0.  8130) 

0.  5767 

5  8.  6  7  8  7 

cent  er_cube.  r 

(  1.0  0  0  0 

0.  7  0  0  2 

0.  5693) 

2.  6940 

42.  0634 

1  ef  t  _  c  u  be .  r 

(  -1.0000 

-  0.  7  0  0  2 

-  0.  5  6  9  3  ) 

0.  5767 

42.  0634 

Notice  the  a  z  and  e  I  reported  are  35  and  25,  which  correspond  to  the  settings  for  those  values  in 
MGED  when  saveview  was  run. 


7.  Scripting  NIRT 


As  mentioned  in  the  output  formatting  section,  hand-copying  NIRT  output  can  be  an 
inconvenient  way  to  store  results,  particularly  in  cases  where  large  numbers  of  rays  will  be  cast. 
In  such  cases,  it  is  possible  to  automate  NIRT  usage  with  scripting. 

7.1  Command  Line  Scripts:  The  e  Option 

The  most  straightforward  approach  to  supplying  NIRT  with  a  series  of  commands  is  to  do  so  in  a 
string  from  the  command  line  using  the  e  option.  The  format  of  such  a  string  is  nirt  -e 
“commandl;  command2; ...  commandn”  model.g  object.  For  example,  to  cast  a  ray  in  the 
negative  z  direction  and  avoid  interactive  mode,  the  following  would  work: 


user  @ma  chine  ~  $  nirt  -b  -  s  -e  “dir  0  0  -1;  s;  q”nirt_example.g  a  I  I  _  c  u  b  e  s .  r 
Origin  (x  y  z)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  6.6  3  3  2  4  9  5  8  )  fh  v  d)  =  (0.0  0"0  0  0.0  0  0  0  0.0  0  0  0  ) 
Direction  (x  y  z)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  -  1.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  9  0.0  0  0  0  0  0  0  0  ) 
Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  At  t  r  i  b 

a  I  I  _  c  u  bes .  r  (  0.0  0  0  0  0.0  0  0  0  1.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 


It’s  important  to  be  aware  that  the  order  of  e  and / options  matters.  They  are  read  in  from  left  to 
right,  and  each  option  is  aware  of  the  effects  of  the  previous  options.  Using  the  gap  format  with 
the  left_and_right_cubes.r  object,  both  orders  of  the  e  and / options  produce  different  results: 
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user  @ma  chine  ~  $  nirt  -b  -  s  -f  g  a  p  2  -e  “s ;  q”  nirt_example.g  left_and_right_cubes.r 

Origin  (x  y  z)  =  (  6.6  3  3  2  4  9  5  8  0.0  0  0  0  0  0  0  0  0.  OOOOOOOO")  (h  v  d)  =  (  o".  OOO'O  O.OO'OO  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0)  (az  el)  =  (0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0) 

Region  Name  Entry  (x  y  z)  LOS  Obliq_in  Attrib 

I  eft_and_ri  ght_cubes.  r  (  3.0000  0.0000  0.0000)  2.0000  O'OOOO 

GAP:  x y z _  i  n  =(  1  0  0)  xyz_out  =(  -  1  0  0)  I  o s  =2 

left_and~right_cubes.r  [  -  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 

user  @ma  chine  ~  $  nirt  -b  -  s  -e  “s ;  q”-f  g  a  p  2  nirt_example.g  left_and_right_cubes.r 

Origin  (x  y  z)  =  (  6.6  3  3  2  4  9  5  8  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0")  (h  v  d)  =  (  o".  OOO'O  O.OO'OO  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  Attrib 

left  and  right  cubes. r  (  3.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  O'OOOO 

I  eft_and_ri  ght_cubes.  r  (  -  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 


In  the  second  case,  the  arguments  to  e  were  executed  before  the  formatting  change  was  reached. 
A  final  illustration  of  this  behavior  uses  multiple  instances  of  the  e  and / options: 

user  @ma  chine  ~  $  nirt  -b  -  s  -e  “s  ”  -  f  g  a  p  2  -e  “s ;  q  ”  nirt_example.g  left_and_right_cubes.r 
Origin  (x  y  z)  =  (  6.6  3  3  2  4  9  5  8  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  Attrib 

left  and  right  cubes. r  (  3.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0  "  0  0  0  0 

left  and  right  cubes. r  (  -  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 

Origin  (x  y  z)  =  (6.6  3  3  2  4  9  5  8  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  Attrib 

I  ef  t  _  a  n  d  _  r  i  ght  _cubes .  r  (  3.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0  "  0  0  0  0 

GAP:  x  y  z  _  i  n  =  (  1  0  0)  xyz_out=(-l  0  0)  I  o  s  =  2 

left_and~right_cubes.r  [  -  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 


Notice  how  the  commands  in  the  first  e  option  are  run  without  the  gap  formatting,  but  the 
command  in  the  second  is  run  with  gap  formatting. 

7.2  Script  Files:  Other  Uses  of  the /Option 

Earlier,  the / option  was  used  to  change  the  output  formatting  of  NIRT.  This  is  only  one  instance 
of  using  scripted  commands  in  files  to  control  NIRT.  The  same  principles  apply  for  any 
command  normally  available  during  an  interactive  NIRT  session. 

Instead  of  hand-copying  the  output  to  a  file,  as  was  done  in  the  previous  example  using  t  i  re.  g , 
a  more  ambitious  goal  is  to  output  the  results  of  several  different  ray  casts  to  a  single  file  without 
manual  copying.  A  script  file  is  thus  defined  as: 


#  testscript:  A  Scripted  NIRT  Example 
bac  kout  1 
di  r  -  1  0  0 
s 

dir  10  0 
s 

q 
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Because  the  intent  is  to  have  only  the  output  in  the  file,  the  s  option  is  supplied  to  the  nirt 
command.  The  output  is  redirected  to  a  file  called  output.txt.* 

nirt  -s  -f  testscript  nirt_example.g  left_and_right_cubes.r  >  output.txt 


The  contents  of  that  file  are  the  text  reports  of  the  two  rays  cast  into  the  model: 


Or  i  g  i  n  ( x  y 
Direction  ( 
Reg i  on 
I  ef  t  _  a  n d_  r  i 
I  ef  t  _  a  n d_  r  i 
Or  i  g  i  n  ( x  y 
Direction  ( 
Re g i  on 
I  ef  t  _  a  nd_  r  i 
left  and  r  i 


z)  =  (  6.6  3  3  2  4  9  5  8  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 
x  y  z)  = 

Na  me 

g  ht  _  c  u  bes 
g  ht  _  c  u  bes 
z)  =  ( -  6 


x  y  z)  = 
Na  me 

g  ht  _  c  u  bes 
g  ht  _  c  u  bes 


-  1.  0  0  0  0  0  0  0  0  0.  0  0  0  0  0  0  0  0  0.  0  0  0  0  0  0  0  0  ) 
Entry  ( x  y  z ) 

r  (  3.  0000  0.  0000  0.  0000) 

r  (  -  1.  0  0  0  0  0.  0  0  0  0  0.  0  0  0  0  ) 

63324958  0.  00000000  0.  00000000)  (  h 

1.  00000000  0.  00000000  0.  00000000)  ( 
Entry  ( x  y  z ) 

r  (  -  3.  0  0  0  0  0.  0  0  0  0  0.  0  0  0  0  ) 

r  (  1.  0000  0.  0000  0.  0000) 


(  az  el  )  =  (  -  0.  0  0  0  0  0  0  0  0  -  0.  0  0  0  0  0  0  0  0) 
LOS  Obi i  q _ i  n  At  t  r i  b 
2.0000  0"0000 
2.0  0  0  0  0.0  0  0  0 
v  d)  =  ( 0.  0000  0.  0000  0.  0000) 
az  el )  =  ( -  1  8  0.  0  0  0  0  0  0  0  0  -  0.  0  0  0  0  0  0  0  0  ) 
LOS  Obi i  q _ i  n  At  t  r i  b 
2.0000  0"0000 
2.0  0  0  0  0.0  0  0  0 


This  is  useful,  but  more  interesting  would  be  the  output  in  csv  format.  Fortunately,  the / option 
can  be  used  multiple  times  in  a  single  nirt  run: 

nirt  -s  -f  csv  -f  testscript  nirt_example.g  left_and_right_cubes.r  >  output. csv 

As  mentioned  in  the  earlier  section,  when  combinations  of  e  and / options  were  used,  using 
multiple  instances  of  the / option  in  this  fashion  requires  paying  attention  to  the  left-to-right 
order.  The  csv  script  in  the  previous  case  is  executed  before  testscript.  The  result  is  the  csv 
equivalent  of  the  preceding  file: 


Ray : 

x  _  o  r  i  g,  y_ori  g,  z_ori  g,  d_ori  g,  h, v, x  _  d i  r, y_di  r,  z_di  r,  az,  el 

6"  6  3  3  2  4  9  5  8,  0.  0  0  0  0  0  0  0  0,  0.  0  0  0  0  0  0  0  0,  0.  0  0  0  0  0  0  0  0,  o"  0  0  0  0  0  0  0  0,  0.  0  0  0  0  0  0  0  0, -  1.  0  0  0  0  0  0  0  0,  0.  0  0  0  0  0.  .  . 


Res  u I  t  s : 

r  e  g  _  n  a  me ,  pat  h_name,  reg_i  d,  x_i  n, y_i  n,  z_i  n,  d_i  n, x  _  o  u  t ,  y  _  o  u  t ,  z_out,  d_out, I  os,  seal  e  d  _ I  os, . . 
”1  eft_and_ri  ght_cubes.  r  ”,  ”/ 1  eft_and_ri  ght_cubes.  r  ”,  1004,  3.  000000,  0.  000000,  0.  000000,  3.  .  .  . 

”1  e  f  t  _  a  n  d  _  r  i  g  h  t  _  c  u  b  e  s .  r  ”,  ”/  I  e  f  t  _  a  n  d  _  r  i  g  h  t  _  c  u  b  e  s .  r  ”,  1  0  0  4,  -  1 .  0  0  0  0  0  0,  0 .  0  0  0  0  0  0,  0 .  0  0  0  0  0  0,  -  .  .  . 

Ray : 

x  _  o  r  i  g,  y_ori  g,  z_ori  g,  d_ori  g,  h, v, x  _  d i  r, y_di  r,  z_di  r,  az,  el 

-  6  3  3  2  4  9  5  8,  0.  0  0  0  0  0  0  0  0,  0  "  0  0  0  0  0  0  0  0,  0  "  0  0  0  0  0  0  0  0,  0.  0  0  0  0  0  0  0  0,  0.  0  0  0  0  0  0  0  0,  1.  0  0  0  0  0  0  0  0,  0.  0  0  0  0  0.  .  . 

Res  u I  t  s : 

r  e  g  _  n  a  me ,  pat  h_name,  reg_i  d,  x_i  n, y_i  n,  z_i  n,  d_i  n, x  _  o  u  t ,  y  _  o  u  t ,  z_out,  d_out, I  os,  seal  e  d  _ I  os, . . 
”1  e  f  t  _  a  n  d  _  r  i  g  h  t  _  c  u  b  e  s .  r  ”,  ”/  I  e  f  t  _  a  n  d  _  r  i  g  h  t  _  c  u  b  e  s .  r  ”,  1  0  0  4,  -  3 .  0  0  0  0  0  0,  0 .  0  0  0  0  0  0,  0 .  0  0  0  0  0  0,  3 .  .  . 
”1  e  f  t  _  a  n  d  _  r  i  g  h  t  _  c  u  b  e  s .  r  ”,  ”/  I  e  f  t  _  a  n  d  _  r  i  g  h  t  _  c  u  b  e  s .  r  ”,  1  0  0  4,  1 .  0  0  0  0  0  0,  0 .  0  0  0  0  0  0,  0 .  0  0  0  0  0  0,  -  1 .  .  . 

As  before,  this  format  is  trivially  imported  into  a  spreadsheet  (figure  22). 


*These  examples  use  a  standard  POSIX-style  output  redirect  to  create  the  file.  If  this  doesn’t  work,  the  script  can  be  edited  to 
use  the  dest  command  instead. 
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Figure  22.  The  f  option  output  file  imported  into  a  spreadsheet. 

7.3  Defining  a  Custom  Reporting  Format 

A  final  example  of  the  use  of  the  scripting  mechanism  is  constructing  a  custom-tailored  report 
format  and  specifying  it  using  the / option.  In  the  case  of  a  custom  file  stored  in  a  user  directory, 
the  full  file  name  needs  to  be  supplied  just  like  any  other  script,  e.g.,  nirt  -f  my_report_format. 
nrt  model.g  item. 

Generally,  it  is  simplest  to  use  one  of  the  predefined  files  as  a  starting  point.  For  example,  if  the 
user  prefers  to  have  commas  between  xyz  coordinates  but  otherwise  wishes  to  use  the  default 
format,  the  d  e  f  a  u  I  t  .  nrt  file  from  the  installed  BRL-CAD  system  is  copied  to  the  local 
directory  and  renamed  d  e  f  a  u  I  t  -  c  o  mma  s .  n  r  t  : 


ma  c  h  i  n  e :  ~  u  s  e  r  $  c  p  /  usr/brl  cad/share/brl  cad/7.  12.  5/ni  rt/defaul  t.  nrt  defaul  t  -  co  mma  s .  n  r  t 

machine:  -  u  s  e  r  $  mo  re  defaul  t  -  co  mma  s .  n  r  t 

#  default,  nrt 

#  Description:  default  -  Standard  NIRT  Reporting  Format 

f  mt  r  “Origin  ( x  y  z )  =  (  %.  8  f  %.  8  f  %.  8  f )  (  h  v  d )  =  (  %.  4  f  %.  4  f  %.  4  f )  \  n  D  i  r  e  c  t  i  o  n  ( x  y  z )  .  .  . 

f  mt  h  “  Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  At  t  r  i  b\  n” 

f  mt  p  “%-  2  0s  (  %9 .  4  f  %9 .  4  f  %9 .  4  f )  %8 .  4  f  %8 .  4  f  %s  \  n  ”  r  e  g  _  n  a  me  x  _  i  n  y  _  i  n  z  _  i  n  I  o  s  o  b  I  i  q  _  i  n .  .  . 

f  mt  m  “Y  o  u  mi  s  s  e  d  the  t  a  r  g  e  t  \  n  ” 

f  mt  o  “OVERLAP:  ‘%s  ’  and  ‘%s  ’  x  y  z  _  i  n  =  (  %g  %g  %g)  I  o  s  =  %g  \  n”ov_regl_name  ov_reg2_name  ov_... 


Next,  the  file  is  edited  to  replace  all  of  the  spaces  in  the  point  strings  with  commas: 
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machine:  -  u  s  e  r  $  mo  re  default-co  mma  s .  n  r  t 

f  mt  r  “Origin  ( x ,  y ,  z )  =  (  %.  8  f ,  %.  8  f ,  %.  8  f )  (  h ,  v ,  d )  =  (  %.  4  f ,  %.  4  f ,  %.  4  f )  \  n  D  i  r  e  c  t  i  o  n  ( x ,  y ,  z .  .  . 

f  mt  h  “  Region  Name  Entry  (x,y,z)  LOS  Obi  i  q  _  i  n  At  t  r  i  b\  n” 

f  mt  p  “%-  2  0s  (  %9 .  4  f ,  %9 .  4  f ,  %9 .  4  f )  %8 .  4  f  %8 .  4  f  %s  \  n  ”  r  e  g  _  n  a  me  x  _  i  n  y  _  i  n  z  _  i  n  I  o  s  o  b  I  i  q  _  i  .  .  . 

f  mt  f 

f  mt  m  “Y  o  u  mi  s  s  e  d  the  t  a  r  g  e  t  \  n  ” 

f  mt  o  “OVERLAP:  ‘%s’and  ‘%s  ’  xy  z_  i  n  =(  %g ,  %g ,  %g )  I  o  s  =  %g  \  n”ov_regl_name  ov_reg2_name  ov... 

f  mt  g  “” 


Running  the  center _cube.r  object: 


machine:  -  u  s  e  r  $  nirt  -s  -b  -f  d  ef  a  u  I  t  -  c  o  mma  s .  n  r  t  nirt_example.g  center_cube.r 
s 


Origin  ( x ,  y ,  z )  = 
Direction  ( x ,  y ,  z ) 
Region  N  a  me 
center  cube.r 


3.  46410162,  0.  00000000,  0.  0000 
=  ( -  1.  0  0  0  0  0  0  0  0,  0.  0  0  0  0  0  0  0  0,  0. 

Entry  (x,y,z) 

(  1.0  0  0  0,  0.0  0  0  0,  0 


0000)  ( h, v,  d)  =  ( 0.  0000,  0.  0000,  0.  0000) 

00000000)  ( az , el )  =(0.00000000,0.00000000) 

LOS  Obi i  q _ i  n  At  t  r i  b 
.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 


Notice  the  commas  now  present  between  points.  This  file  can  be  saved  and  reused  on  any  NIRT 
task. 

Note:  If  a  user  wishes  to  save  the  current  session  configuration  of  an  interactive  command  line 
NIRT  session  at  any  time,  they  can  always  use  the  dump  interactive  command  to  print  out 
a  script  file  that  contains  all  the  relevant  commands  required  to  restore  a  specific 
configuration.  By  default,  this  file  is  called  n  i  rtstate.  The  stateflle  interactive 
command  is  used  to  change  that  name  if  desired.  If  a  user  has  used  in-session  commands 
to  alter  formatting  but  wants  to  preserve  them  for  later  use  or  as  a  starting  point  for  a  new 
report  format,  the  output  of  dump  is  an  excellent  starting  point. 

7.4  Customizing  Report  Output  in  MGED 

The  Query  Ray  Control  Panel  discussed  earlier  also  provides  access  to  the  reporting  logic  used 
by  MGED  when  calling  NIRT,  but  it  does  not  provide  any  graphical  aid  when  it  comes  to  laying 
out  the  formatting.  All  layout  logic  must  be  defined  with  the  same  syntax  already  seen  for  the 
script  files.  Customizations  of  this  logic  in  MGED  are  done  using  the  Advanced  option  in  the 
lower  right  comer  of  the  Query  Ray  Control  Panel,  which  brings  up  the  Query  Ray  Advanced 
Settings  dialog  box  (figure  23). 

Note  also  the  last  line  of  this  dialog  box,  which  provides  a  place  for  script  commands  to  be 
executed  before  the  internal  s  command  is  ran.  It  functions  just  like  the  -e  option  on  the  normal 
command  line,  including  the  syntax  of  separating  all  commands  except  the  last  one  with 
semicolons.  This  is  useful  for  setup  not  possible  in  normal  command  line  operation,  as 
illustrated  in  the  next  section. 
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Figure  23.  MGED’s  Query  Ray  Advanced  Settings  dialog  box. 

7.5  Reporting  Attributes  in  MGED:  Advanced  Formatting  and  Scripting 

As  mentioned  earlier,  reporting  attributes  with  NIRT  inside  of  MGED  is  more  involved  than  the 
strictly  command  line  interface  allows.  In  default  NIRT  reporting  inside  MGED,  the  attributes 
column  is  not  even  listed.  Attributes  can  be  reported  with  NIRT  in  MGED,  but  it  requires 
custom  formatting  and  scripting. 

The  first  step  is  to  open  the  Query  Ray  Advanced  Settings  dialog  box.  Examining  the  default 
NIRT  formatting  file  used  on  the  command  line  reveals  that  the  partition  formatting  string  needs 
a  %s  variable  added  and  the  attributes  variable  in  position  to  be  supplied  to  the  %s.  Also,  the 
Attrib  column  header  is  added  to  Head  (figure  24). 


Figure  24.  Query  Ray  Advanced  Settings  dialog  box  showing  changes  to  values  (white 
highlight). 


The  second  step  is  to  use  the  Script  line  in  this  dialog  box  to  add  rgb  to  the  attributes  list. 
Because  the  script  line  is  run  before  MGED  sends  the  s  command,  the  attributes  list  will  be 
updated  by  the  time  the  ray  is  cast  and  the  subsequent  report  is  generated. 
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Figure  25.  Adding  commands  to  the  Script  line  in  the  advanced  settings  dialog. 

Unless  graphical  visualization  is  needed,  it  is  probably  simpler  to  work  from  the  NIRT 
interactive  command  line  in  cases  where  a  lot  of  adjustment  of  attribute  reporting  is  needed. 
However,  if  MGED  is  needed,  this  technique  will  allow  custom  reports  inside  of  MGED  that 
include  attributes. 

7.6  Available  Information  for  Inclusion  in  Reports 

There  are  many  cases  where  the  user  may  want  to  change  what  NIRT  is  reporting  instead  of,  or 
in  addition  to,  the  formatting  of  the  reports.  NIRT  internally  defines  values  that  it  supports  as 
output  options,  most  of  which  are  not  reported  in  the  default  format  for  the  sake  of  brevity  and 
clarity.  It  also  defines  “events”  corresponding  to  various  model  geometric  states  encountered  by 
the  ray,  which  are  used  to  trigger  print  events  (table  4).  The  available  variables  pertain  to  the 
ray,  partitions,  overlaps,  and  gaps.  Other  event  options  typically  use  only  labeling  strings.  The 
variables  are  listed  in  appendix  B  and  can  be  used  to  change  reported  information.  The  csv 
output  format  is  one  example  of  such  use. 

Table  4.  Report  event  types. 


Event 

Description 

r 

Ray.  A  ray  is  cast.  The  formatting  associated  with  r  will  print 
regardless  of  whether  a  region  is  encountered. 

h 

Header.  First  output  after  a  ray  hits  anything.  Formatting  at  h  is 
output  once  per  ray. 

P 

Partition.  Output  for  each  region  encountered  by  the  ray.  Typically, 
this  will  be  where  most  of  the  information  about  a  model  is  reported. 

f 

Footnote.  Last  output  statement  after  a  ray  hits  anything;  a  footnote 
line  after  the  ray  has  completed  its  evaluations;  once  per  ray. 

g 

Gap.  Output  written  once  for  each  gap  the  ray  may  encounter. 

m 

Miss.  If  triggered,  prints  a  message  that  nothing  was  hit;  maximum 
once  per  ray. 

0 

Overlap.  Output  written  once  for  each  overlap  along  the  ray. 
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8.  Summary 


•  NIRT  is  the  standard,  interactive  ray  trace  query  tool  used  for  obtaining  precise,  detailed 
information  about  specific  areas  of  a  model  via  individual  ray  queries. 

•  NIRT  offers  a  wide  variety  of  formatting  options  for  various  analysis  needs  as  well  as 
support  for  custom  formats. 

•  Running  NIRT  within  MGED  offers  additional  graphical  feedback  not  available  when  run 
outside  of  MGED. 

•  NIRT  provides  both  command-line  and  file-based  scripting  to  allow  for  powerful, 
automated,  custom  analyses. 
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Intentionally  left  blank. 
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Appendix  A.  Debugging  Options 


In  cases  where  problems  are  being  encountered,  it  is  possible  to  use  debugging  options  to  print 
additional  information  related  to  the  raytracing  process.  NIRT  exposes  two  levels  of  debugging: 
the  core  raytracing  library  and  NIRT  itself. 

A.l  librt  Debugging  Information 

In  cases  where  detailed  behavior  of  the  core  raytracing  routines  is  of  interest,  it  is  possible  to  use 
the  x  (lower  case  “x”)  option  to  print  additional  diagnostic  messages.*  (See  the  librt  header  files 
for  more  details  about  the  very  extensive  debugging  options  provided.) 

ma  chine:-  u  s  e  r  $  nirt  -s  -b  -x  0x002  -e  “s ;  q”  nirt_example.g  center_cube.r 

**********  s  h00t  r  ay  c  p  u  =  o  0,0  I  v  I  =  0  a_onehit=0  (NIRT  ray) 

Pnt  (3.4641016151377543864,  0,  0) 

Di  r  (  -  1,  0,  0) 

. Partition  list  passed  to  a _ h i t ( )  routine 

00604d50:  PT  center  cube.s  ( ARB8 #0 )  center  cube.s  ( ARB8 #0 )  (  2.4  6  4  1,4.4  6  4  1  ) 

I  n HI T  di  st  =2.  4  6  4  1  (surf  5) 

Out  HIT  di  st  =4.  4  6  4  1  (surf  4) 

Pri  mi  fives:  center_cube.s, 

Untrimmed  Segments  spanning  this  interval: 

0680d600:  SEG  c  e  n  t  e  r  _  c  u  b  e .  s  (  2.4  6  4  1,4.4  6  4  1  )  s  t  _  b  i  t  =0  xray#  =  0 
Region:  /center_cube.r 


Origin  (x  y  z)  =  (  3.4  6  4  1  0  1  6  2  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 
Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0)  (az  el)  =  (0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 
Region  Name  Entry  (x  y  z)  LOS  Obliq_in  Attrib 

cent  er_cube.  r  (  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 

. shootray  c  p  u  =0  0,0  I  v  I  =0  (NIRT  ray)  HIT  r  e  t  =1 


A.2  NIRT  Debugging  Information 

NIRT  itself  also  provides  debugging  information.  It  is  accessed  using  the  X  option.*^  NIRT 
provides  five  different  debug  flags,  as  seen  in  nirt.h: 

/**  FLAG  VALUES  FOR  ni  rt  debug  */ 

#def i  ne  DEBUG  I  NTERACT  0x001 

#def i  ne  DEBUG  SCRI  PTS  0x002 

#def i  ne  DEBUG” MAT  0x004 

#def i  ne  DEBUG  BACKOUT  0x008 

#def i  ne  DEBUG  HI TS  0x010 


OxOOl  and  0x002  pertain  to  interaction  and  scripts,  respectively: 


*librt’s  diagnostic  setting  can  also  be  set  in  the  interactive  environment  with  the  libdebug  command. 
^The  nirt  level  diagnostics  can  be  set  in  the  interactive  environment  with  the  debug  command. 
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ma  chine:-  u  s  e  r  $  nirt  -s  -b  -X  0x001  -  e  “s ;  q”  nirt_example.g  center_cube.r 

i  nt  e  r  a  c  t  (  READI  NG_  STRI  NG,  6  0  3  c  10)  .  .  . 

sgetc((nul  I  ))  ‘(null)’  ‘(null)’...  initializing 

s  g  et  c  ( s ;  q )  ‘(null)’  ‘(null)’...  initializing 

returning  ‘s’  ( o  1 6  3 ) 

line_buffer[0]  =  ‘s’  ( o  1 6  3 ) 

sgetc(s;  q)  ‘s ;  q’  q  .  .  returning  ’  ( o  7  3 ) 

Line  buffer  contains  ‘s’ 

Origin  (x  y  z)  =  (3.4  6  4  1  0  1  6  2  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0)  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obliq_in  Attrib 

cent  er_cube.  r  (  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 

sget  c(  s;  q)  ‘s ;  q  ’  4  q  ’.  .  .  returning  ‘  ‘  ( o  4  0 ) 

Ski  ppi  ng  4  4 

sgetc(s;  q)  4s ;  q’  4q  ’.  .  .  returning  4q  ’  ( o  1 6 1 ) 
line_buffer[0]  =  4q  ’  ( o  1 6 1 ) 
sget  c(  s;  q)  4s ;  q’  4\  .  .  ret  ur  ni  ng  EOS 
Line  buffer  contains  4q  ’ 


ma  chine:  -  u  s  e  r  $  nirt  -s  -b  -X  0x002  -  e  44s;  q”nirt_example.g  center_cube.r 

i  nt  e  r  a  c  t  (  READI  NG_  STRI  NG,  6  0  3  c  10)  .  .  . 

s  g et  c  (  (  n u  I  I  )  )  ‘(null)’  ‘(null)’...  initializing 

s  g et  c  ( s ;  q )  ‘(null)’  ‘(null)’...  initializing 

returning  4s  ’  ( o  1 6  3 ) 

line_buffer[0]  =  4s  ’  ( o  1 6  3 ) 

sgetc(s;  q)  4s ;  q’  4;  q ’.  .  .  returning  4;  ’  ( o  7  3 ) 

Line  buffer  contains  4s  ’ 

Origin  (x  y  z)  =  (3.4  6  4  1  0  1  6  2  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  Attrib 

cent  er_cube.  r  (  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 

sget  c(  s;  q)  4s ;  q  ’  4  q  ’.  .  .  returning  4  4  ( o  4  0 ) 

Ski  ppi  ng  4  4 

sgetc(s;  q)  4s ;  q’  4q  ’.  .  .  returning  4q  ’  ( o  1 6 1 ) 
line_buffer[0]  =  4q  ’  ( o  1 6 1 ) 
sget  c(  s;  q)  4s ;  q’  4’.  .  .  ret  ur  ni  ng  EOS 
Line  buffer  contains  4q  ’ 

user@l  ocal  host  $  nirt  -s  -b  -X  0x002  -e  44s;  q”  ni  rt_exampl  e.  g  center_cube.r 

. The  command  -  line  scripts . 

1 .  script  string  4s ;  q  ’ 


. The  command  -  line  scripts 

1 .  script  string  4s ;  q  ’ 


At  t  e  mpt  i  n  g  to  run  literal  4s ;  q  ’ 

Origin  (x  y  z)  =  (3.4  6  4  1  0  1  6  2  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 
Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 
Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  Attrib 

cent  er_cube.  r  (  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 


The  0x004  DEBUG_MAT  flag  pertains  to  the  M  option  seen  earlier  in  the  saveview  MGED 
command  example  that  supplies  a  matrix  for  NIRT  to  read.  Adding  the  debug  option  to  the 
script  triggers  a  printout  of  the  matrix: 
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#!  /  b  i  n /  s  h 

nirt  -M  -X  0x004  ni  r  t  _  ex  amp  I  e.  g  center_cube.r  <  <  E  0  F 

orientation  5.  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  e  -  0  1  5 .  0  0  0  0  0  0  0  0  0  0  0  0  0  0  1  e  -  0  1  5 .  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  e  -  0  1  4.  9  9  9  9  9  9  9  9  9  9  9  9  9  9  9  e  - 
01; 

eye  pt  0.  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  e +0  0  0 .  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  e +0  0  0 .  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  e +0 0 ; 


ma  chine:-  u  s  e  r  $  sh  tsv. script 
MAT  R I  X  view  ma  t  r  i  x  : 


0.  000 

1. 

000 

0.  000 

0.  000 

0.  000 

0. 

000 

1.  000 

0.  000 

1.  000 

0. 

000 

-  0.  000 

0.  000 

0.  000 

0. 

000 

0.  000 

1.  000 

Origin  (x  y  z)  =  (0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 
Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  -  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (az  el)  =  (  0.0  0  0  0  0  0  0  0  -  0.0  0  0  0  0  0  0  0  ) 
Region  Name  Entry  (x  y  z)  LOS  Obliq_in  Attrib 

cent  er_cube.  r  (  1.0  0  0  0  0.0  0  0  0  -  0.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 


DEBUG  BACKOUT  and  DEBUG  HITS  pertain  to  the  backout  option  and  geometry  hits: 


ma  chine:  -  u  s  e  r  $  nirt  -s  -b  -X  0x008  -e  “s ;  q”  ni  rt_exampl  e.  g  center_cube.r 
Backing  out  3.4  6  4  1  units  to  (  3.4  6  4  1  0  0  ),  shooting  dir  is  (-1  0  0) 

Origin  (x  y  z)  =  (  3.4  6  4  1  0  1  6  2  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  )  (h  v  d)  =  (  0.0  0  0  0  0.0  0  0  0  0.0  0  0  0  ) 

Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0)  (az  el)  =  (0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0) 

Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  Attrib 

cent  er_cube.  r  (  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 

ma  chine:  -  u  s  e  r  $  nirt  -s  -b  -X  0x010  -e  “s ;  q”  ni  rt_exampl  e.  g  center_cube.r 
Origin  (x  y  z)  =  (  3.4  6  4  1  0  1  6  2  0.0  0  0  0  0  0  0  0  0.  OOOOOOOO")  (h  v  d)  =  (0.0"0  0  0  0.0  0  0  0  0.0  0  0  0  ) 
Direction  (x  y  z)  =  (-  1.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0)  (az  el)  =  (0.0  0  0  0  0  0  0  0  0.0  0  0  0  0  0  0  0  ) 
Region  Name  Entry  (x  y  z)  LOS  Obi  i  q  _  i  n  Attrib 

Partition  1  entry:  (1,  0,  0)  exit:  (-1,  0,  0) 

cent  er_cube.  r  (  1.0  0  0  0  0.0  0  0  0  0.0  0  0  0  )  2.0  0  0  0  0.0  0  0  0 
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Intentionally  left  blank. 
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Appendix  B.  Report  Format  Variable  Listings 
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Table  B-l .  Ray  variables. 


Command 

Variables 

x_orig 

x  coordinate  of  ray  origination  point 

y_orig 

y  coordinate  of  ray  origination  point 

z_orig 

z  coordinate  of  ray  origination  point 

dorig 

d  coordinate  of  ray  origination  point 

h 

h  coordinate  for  the  entire  ray 

V 

v  coordinate  for  the  entire  ray 

xdir 

x  component  of  direction  vector 

ydir 

y  component  of  direction  vector 

zdir 

z  component  of  direction  vector 

a 

Azimuth  of  view  (i.e.,  of  ray  direction) 

e 

Elevation  of  view  (i.e.,  of  ray  direction) 

Table  B-2.  Partition  variables. 


Command 

Variables 

attributes 

A  string  variable  consisting  of  the  names  and  values  of  the  attributes 
requested  by  the  attr  interactive  command  or  the  -A  command  line 

option 

x_in 

x  coordinate  of  entry  into  current  region 

yin 

y  coordinate  of  entry  into  current  region 

z_in 

z  coordinate  of  entry  into  current  region 

d_in 

d  coordinate  of  entry  into  current  region 

xout 

x  coordinate  of  exit  from  current  region 

yout 

y  coordinate  of  exit  from  current  region 

zout 

z  coordinate  of  exit  from  current  region 

dout 

d  coordinate  of  exit  from  current  region 

los 

Line-of-sight  distance  through  current  region 

scaled_los 

Scaled  line  of  sight:  product  of  line-of-sight  distance  through  current 
region  and  region  soliditya  (sometimes  called  “percent  LOS”) 

pathname 

Full  path  name  of  current  region 

regname 

Name  of  current  region 

regid 

Region  ID  of  current  region 

claimantcount 

Number  of  regions  claiming  this  partition  (i.e.,  participating  in  a 
retained  overlap) 

claimant_list 

Space-separated  list  of  names  of  regions  claiming  this  partition  (i.e., 
participating  in  a  retained  overlap) 

claimantlistn 

Same  as  claimant  list,  except  that  it  is  newline-  rather  than  space- 

separated 

obliq_in 

Entry  obliquity  for  current  region 

obliq_out 

Exit  obliquity  for  current  region 

nm  x  in 

x  component  of  entry  normal  vector 

nm  y  in 

y  component  of  entry  normal  vector 

nmzin 

z  component  of  entry  normal  vector 

nmhin 

h  component  of  entry  normal  vector 
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Table  B-2.  Partition  variables  (continued). 


nm  v  in 

v  component  of  entry  normal  vector 

nm  d  in 

d  component  of  entry  normal  vector 

nm  x  out 

x  component  of  exit  normal  vector 

nmyout 

y  component  of  exit  normal  vector 

nmzout 

z  component  of  exit  normal  vector 

nmhout 

h  component  of  exit  normal  vector 

nmvout 

v  component  of  exit  normal  vector 

nmdout 

d  component  of  exit  normal  vector 

surfnumin 

Entry-surface  ID  of  entry  solid 

surfnumout 

Exit-surface  ID  of  exit  solid 

aRegion  solidity  refers  to  a  thickness  equivalence  factor  often  used  to  simulate  material  properties 
like  density. 


Table  B-3.  Overlap  variables. 


Command 

Overlap  Variables 

ovreglname 

Name  of  one  of  the  overlapping  regions 

ov_reg2_name 

Name  of  the  other  overlapping  region 

ov_regl_id 

Region  ID  of  one  of  the  overlapping  regions 

ov_reg2_id 

Region  ID  of  the  other  overlapping  region 

ov_sol_in 

Name  of  one  of  the  overlapping  solids 

ovsolout 

Name  of  the  other  overlapping  solid 

ov_los 

Line-of- sight  distance  through  the  overlap 

ov_x_in 

x  coordinate  of  entry  into  overlap 

ovyin 

y  coordinate  of  entry  into  overlap 

ov_z_in 

z  coordinate  of  entry  into  overlap 

ov_d_in 

d  coordinate  of  entry  into  overlap 

ovxout 

x  coordinate  of  exit  from  overlap 

ov_y_out 

y  coordinate  of  exit  from  overlap 

ovzout 

z  coordinate  of  exit  from  overlap 

ovdout 

d  coordinate  of  exit  from  overlap 

Table  B-4.  Gap  variables. 


Command 

Variables 

xgapin 

x  coordinate  of  entry  into  gap 

y_gap_in 

y  coordinate  of  entry  into  gap 

zgapin 

z  coordinate  of  entry  into  gap 

gaplos 

Line-of-sight  distance  through  gap 
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NO.  OF 

COPIES  ORGANIZATION 


1  DEFENSE  TECHNICAL 
(PDF  INFORMATION  CTR 
only)  DTIC  OCA 

8725  JOHN  J  KINGMAN  RD 
STE  0944 

FORT  BEL  VOIR  VA  22060-6218 

1  DIRECTOR 

US  ARMY  RESEARCH  LAB 
IMNE  ALC  HRR 
2800  POWDER  MILL  RD 
ADELPHI  MD  20783-1 197 

1  DIRECTOR 

US  ARMY  RESEARCH  LAB 
AMSRD  ARL  Cl  OK  TL 
2800  POWDER  MILL  RD 
ADELPHI  MD  20783-1 197 

1  DIRECTOR 

US  ARMY  RESEARCH  LAB 
AMSRD  ARL  Cl  OK  PE 
2800  POWDER  MILL  RD 
ADELPHI  MD  20783-1 197 


ABERDEEN  PROVING  GROUND 
1  DIR  USARL 

AMSRD  ARL  Cl  OK  TP  (BLDG  4600) 
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NO.  OF 

COPIES  ORGANIZATION 

1  ASST  SECY  ARMY 
(CD  ACQSTN  LOGISTICS  &  TECH 
only)  S AAL  ZP  RM  2E66 1 

103  ARMY  PENTAGON 
WASHINGTON  DC  20310-0103 

1  ASST  SECY  ARMY 
(CD  ACQSTN  LOGISTICS  &  TECH 
only)  SAAL  ZS  RM  3E448 

103  ARMY  PENTAGON 
WASHINGTON  DC  20310-0103 

1  DIRECTOR  FORCE  DEV 
(CD  DAPR  FDZ 
only)  RM  3A522 

460  ARMY  PENTAGON 
WASHINGTON  DC  20310-0460 

1  US  ARMY  TRADOC  ANL  CTR 
ATRC  W 
A  KEINTZ 

WSMRNM  88002-5502 

1  USARL 
AMSRD  ARL  SL  E 
R  FLORES 

WSMRNM  88002-5513 

2  SURVICE  ENGRG 
J  DUVALL 

4695  MILLENNIUM  DR 
BELCAMP  MD  21017-1505 

4  QUANTUM  RSRCH  INTRNTL 
M  JERNIGAN 
2014  TOLLGATE  RD 
STE  203 

BEL  AIR  MD  21015 

2  APPLIED  RSRCH  ASSOC 
A  ROSS 

4690  MILLENNIUM  DR 
STE  210 

BELCAMP  MD  21017-1505 

2  MANTECH  SRS  TECHLGY 
T  BROWDER 

1984  LEWIS  TURNER  BLVD 
FORT  WALTON  BEACH  FL  32547 


NO.  OF 

COPIES  ORGANIZATION 

2  NVL  SURFC  WARFARE  CTR 
DAHLGREN 
D  DICKINSON  G24 
6138  NORC  AVE  STE  313 
DAHLGREN  VA  22448-5157 

1  AFRL 

MUNITIONS  DIRCTRT 
N  GAGNON 

101  W  EGLIN  BLVD  STE  309 
EGLIN  AFB  FL  32542 

1  AFRL  RWAL 
S  STANDLEY 

101  W  EGLIN  BLVD  STE  307 
EGLIN  AFB  FL  32542 

1  ASC  ENDA  VULNERABILITY  TEAM 
T  STALEY 

1970  MONAHAN  WAY  BLDG  1 1 A 
RM  018V 

WRIGHT  PATTERSON  AFB  OH 
45433-7210 


ABERDEEN  PROVING  GROUND 

1  US  ARMY  DEV  TEST  COM 

CSTE  DTC  TT  T 
3 14  LONGS  CORNER  RD 
APG  MD  21005-5055 

1  US  ARMY  EVALUATION  CTR 

CSTE  AEC  SVE 
R  LAUGHMAN 
4120  SUSQUEHANNA  AVE 
APG  MD  21005-3013 

36  DIR  USARL 

AMSRD  ARL  SL 
J  BEILFUSS 
J  FEENEY 
J  FRANZ 
M  STARKS 
P  TANENBAUM 
AMSRD  ARL  SL  B 
G  MANNIX 
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NO.  OF 

COPIES  ORGANIZATION 


AMSRD  ARL  SL  BA 
D  FARENWALD  (5  CPS) 
A  VOGT  (5  CPS) 
AMSRD  ARL  SL  BD 
R  GROTE  (2  CPS) 
AMSRD  ARL  SL  BE 
M  PERRY  (2  CPS) 
AMSRD  ARL  SL  BG 
P  MERGLER  (3  CPS) 
AMSRD  ARL  SL  BS 
S  SNEAD  (10  CPS) 
AMSRD  ARL  SL  BW 
L  ROACH  (3  CPS) 
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NO.  OF 

COPIES  ORGANIZATION 


2  NO  PRINS  MAURITS  LAB 
S  PRONK 
W  BOKKERS 
PO  BOX  45 

2280  AA  RIJSWIJK  ZH 
THE  NETHERLANDS 

1  INDUSTRIE  ANLAGEN 

BETRIEBSGESELLSCHAFT  MBH  IABG 

D  ROSSBERG 

EIN STEINSTRAS SE  20 

85521  OTTOBRUNN 

GERMANY 
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Intentionally  left  blank. 
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